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
/**
* Decks — the pure, dependency-free half of the card-deck designer.
*
* Owns the deck alphabet (`playing` | `tarot`), the card roster each kind
* mints on creation, the layout clause and face-orientation prompt each kind
* renders with, the render prompt composition (deck style → layout → face
* orientation → card subject), and the completion math the index page and the
* detail header both show. Keeping this leaf
* import-free lets `client/src/lib/decks.js` re-export it verbatim, so the
* client never carries a second copy of the roster or the completion rule.
*
* Zod schemas for the routes live in `deckValidation.js`; DB access lives in
* `services/decks.js`.
*/
import { aspectRatioPhrase } from './aspectRatio.js';
import { composeStyledPrompt } from './composeStyledPrompt.js';
import { buildVisualStyleClause, universeVisualStyleTokens } from './universeVisualStyle.js';
export const DECK_KIND = Object.freeze({ PLAYING: 'playing', TAROT: 'tarot' });
export const DECK_KINDS = Object.freeze(Object.values(DECK_KIND));
export const DECK_KIND_LABELS = Object.freeze({
[DECK_KIND.PLAYING]: 'Playing cards',
[DECK_KIND.TAROT]: 'Tarot',
});
const trimmed = (v) => (typeof v === 'string' ? v.trim() : '');
// Face orientation is a deck-wide property because every card in a physical
// deck must agree on how its indices read. Playing cards default to the
// conventional two-way face; tarot defaults to one-way because its title and
// illustration are normally read from one direction.
export const DECK_CARD_ORIENTATION = Object.freeze({
STANDARD: 'standard',
ONE_WAY: 'one-way',
});
export const DECK_CARD_ORIENTATIONS = Object.freeze(Object.values(DECK_CARD_ORIENTATION));
export const DECK_CARD_ORIENTATION_LABELS = Object.freeze({
[DECK_CARD_ORIENTATION.STANDARD]: 'Standard two-way (mirrored indices)',
[DECK_CARD_ORIENTATION.ONE_WAY]: 'One-way (upright indices)',
});
export const DEFAULT_DECK_CARD_ORIENTATION = Object.freeze({
[DECK_KIND.PLAYING]: DECK_CARD_ORIENTATION.STANDARD,
[DECK_KIND.TAROT]: DECK_CARD_ORIENTATION.ONE_WAY,
});
// These are intentionally explicit rather than relying on a model to infer
// what "symmetrical" means. In particular, a bottom-right upright 6 is easily
// read as a 9 after the physical card is turned around.
const BUILT_IN_CARD_ORIENTATION_PROMPTS = Object.freeze({
[DECK_CARD_ORIENTATION.STANDARD]: 'Standard two-way playing-card face, vertically mirrored: the top-left rank and suit index is upright, while the matching bottom-right index is an exact 180-degree rotation and reads upside down from the top edge; the two indices must be the same glyph and rank, so a six remains a six and never becomes a nine',
[DECK_CARD_ORIENTATION.ONE_WAY]: 'One-way card face: all rank, suit and title markings share one upright reading direction; the top-left and bottom-right indices face the same way, with no 180-degree rotation or inverted duplicate',
});
const BUILT_IN_CARD_ORIENTATION_NEGATIVES = Object.freeze({
[DECK_CARD_ORIENTATION.STANDARD]: 'upright duplicate bottom-right index, mismatched rank indices, six rendered as nine, incorrect glyph rotation',
[DECK_CARD_ORIENTATION.ONE_WAY]: 'upside-down index, rotated bottom-right rank, inverted duplicate, mirrored lettering',
});
/** The effective face orientation, or null for a non-deck-shaped prompt input. */
export function deckCardOrientation(deck) {
if (DECK_CARD_ORIENTATIONS.includes(deck?.cardOrientation)) return deck.cardOrientation;
return DEFAULT_DECK_CARD_ORIENTATION[deck?.kind] || null;
}
/** The built-in orientation prompt, ignoring a deck's authored override. */
export function defaultDeckCardOrientationPrompt(deck) {
const orientation = deckCardOrientation(deck);
return orientation ? BUILT_IN_CARD_ORIENTATION_PROMPTS[orientation] : '';
}
/** The effective orientation prompt: an authored override or the safe default. */
export function deckCardOrientationPrompt(deck) {
const override = trimmed(deck?.cardOrientationPrompt);
return override || defaultDeckCardOrientationPrompt(deck);
}
/** The matching built-in negative guard; custom positive prompts own their negatives. */
export function deckCardOrientationNegativePrompt(deck) {
if (trimmed(deck?.cardOrientationPrompt)) return '';
const orientation = deckCardOrientation(deck);
return orientation ? BUILT_IN_CARD_ORIENTATION_NEGATIVES[orientation] : '';
}
// Fallback portrait size for an unrecognized deck kind (2:3, matching the
// universe canon thumbnail convention `EntryThumbSlot` was built around).
// Real decks use `DECK_CARD_SIZE_BY_KIND` below instead.
export const DECK_CARD_SIZE = Object.freeze({ width: 1024, height: 1536 });
// Per-edge bounds for a deck's card size. `deckValidation.js` builds its zod
// `cardSizeSchema` from these and the client's size inputs clamp to them, so
// the form can't submit a value the PATCH would 400 on and neither side holds
// its own copy of the numbers.
export const DECK_CARD_SIZE_MIN = 256;
export const DECK_CARD_SIZE_MAX = 4096;
// Per-kind default card size, at each kind's true physical trim ratio rather
// than the generic 2:3 fallback above — poker cards are 2.5"×3.5" (5:7),
// tarot cards are 2.75"×4.75" (11:19). Both hold the same 1536 long edge as
// the generic default so render cost/detail stays comparable. Thumbnails size
// their slot to this ratio and contain the image (`deckCardSize` /
// `deckCardAspectStyle`) so the rank, index, title banner and decorative
// border stay in frame — a 2:3 `object-cover` box crops playing cards on the
// sides and tarot cards top/bottom. A deck's own `cardSize` (persisted
// per-deck, see `services/decks.js`) always wins — this is only the value
// new decks mint.
export const DECK_CARD_SIZE_BY_KIND = Object.freeze({
[DECK_KIND.PLAYING]: Object.freeze({ width: 1096, height: 1536 }),
[DECK_KIND.TAROT]: Object.freeze({ width: 888, height: 1536 }),
});
const isPositiveEdge = (value) => Number.isFinite(value) && value > 0;
/**
* The canvas a deck's cards actually render at: the persisted `cardSize` when
* both edges are positive, otherwise that kind's trim, otherwise the 2:3
* fallback. One read so the grid, drawer, sample thumbs and render-target
* summary cannot disagree about the box.
*/
export function deckCardSize(deck) {
const width = Number(deck?.cardSize?.width);
const height = Number(deck?.cardSize?.height);
if (isPositiveEdge(width) && isPositiveEdge(height)) return { width, height };
return { ...(DECK_CARD_SIZE_BY_KIND[deck?.kind] || DECK_CARD_SIZE) };
}
/** Inline `style.aspectRatio` for a card thumbnail, derived from `deckCardSize`. */
export function deckCardAspectStyle(deck) {
const { width, height } = deckCardSize(deck);
return { aspectRatio: `${width} / ${height}` };
}
// The one card every deck has that is not a face: the shared back design.
export const DECK_BACK_KEY = 'back';
// Card render states derived from the persisted render record + image refs.
export const CARD_STATUS = Object.freeze({
EMPTY: 'empty', // no prompt yet
PROMPTED: 'prompted', // prompt authored, nothing rendered
QUEUED: 'queued',
RUNNING: 'running',
RENDERED: 'rendered',
FAILED: 'failed',
});
// Per-kind layout clause. Every card of a deck shares it (editable on the deck)
// so the whole set reads as ONE physical object — same border, same index
// treatment — while the card prompt carries only the subject.
//
// The framing phrase is DERIVED from the kind's canvas, never written beside
// it: these clauses kept telling the model "2:3 portrait" after the per-kind
// sizes moved to each card's true trim (5:7 and 11:19), so the prompt and the
// canvas disagreed about the shape being drawn. Deriving means changing a
// canvas changes the sentence, and the two cannot drift apart again.
const layoutClauseFor = {
[DECK_KIND.PLAYING]: (framing) => `Complete playing-card face, ${framing}, ornate decorative border, the rank and suit index placed in the top-left and bottom-right corners, symmetrical composition`,
[DECK_KIND.TAROT]: (framing) => `Complete tarot card, ${framing}, decorative framed border, the card title lettered in a banner along the bottom edge, symbolic centered composition`,
};
export const DEFAULT_LAYOUT_PROMPT = Object.freeze(Object.fromEntries(
DECK_KINDS.map((kind) => {
// Loud at import rather than silent at render: a kind with no clause used to
// resolve to `undefined` here and reach `services/decks.js`, whose
// `|| ''` fallback would mint every card of that deck with NO shared layout
// at all — a whole deck rendered wrong before anyone noticed the gap.
const clause = layoutClauseFor[kind];
if (!clause) throw new Error(`Deck kind ${kind} has no DEFAULT_LAYOUT_PROMPT clause`);
const size = DECK_CARD_SIZE_BY_KIND[kind] || DECK_CARD_SIZE;
return [kind, clause(aspectRatioPhrase(size.width, size.height))];
}),
));
const PLAYING_SUITS = Object.freeze([
{ key: 'spades', name: 'Spades', symbol: '♠' },
{ key: 'hearts', name: 'Hearts', symbol: '♥' },
{ key: 'diamonds', name: 'Diamonds', symbol: '♦' },
{ key: 'clubs', name: 'Clubs', symbol: '♣' },
]);
const PLAYING_RANKS = Object.freeze([
{ key: 'A', name: 'Ace' }, { key: '2', name: 'Two' }, { key: '3', name: 'Three' },
{ key: '4', name: 'Four' }, { key: '5', name: 'Five' }, { key: '6', name: 'Six' },
{ key: '7', name: 'Seven' }, { key: '8', name: 'Eight' }, { key: '9', name: 'Nine' },
{ key: '10', name: 'Ten' }, { key: 'J', name: 'Jack' }, { key: 'Q', name: 'Queen' },
{ key: 'K', name: 'King' },
]);
const PLAYING_SUIT_SHAPES = Object.freeze({
spades: Object.freeze({ color: 'black', noun: 'spade', shape: 'pointed leaf with a narrow stem' }),
hearts: Object.freeze({ color: 'red', noun: 'heart', shape: 'two rounded lobes and a pointed bottom' }),
diamonds: Object.freeze({ color: 'red', noun: 'diamond', shape: 'pointed lozenge' }),
clubs: Object.freeze({ color: 'black', noun: 'club', shape: 'three rounded lobes and a short stem' }),
});
// The traditional pip layout for each numbered rank. Naming the arrangement
// gives an image model a concrete structure to fill, which it follows far more
// reliably than a bare count — "exactly 6" alone kept rendering 8–10 pips.
const PIP_LAYOUTS = Object.freeze({
2: 'one pip at the top center and one at the bottom center',
3: 'a single vertical column of three pips down the center',
4: 'two vertical columns of two pips, one pip near each corner of the central field',
5: 'two vertical columns of two pips plus one pip in the exact center',
6: 'two vertical columns of three pips, left and right, with nothing between them',
7: 'two vertical columns of three pips plus one pip centered between the top and middle rows',
8: 'two vertical columns of three pips plus two center pips, one between the top and middle rows and one between the middle and bottom rows',
9: 'two vertical columns of four pips plus one pip in the exact center',
10: 'two vertical columns of four pips plus two center pips, one in the upper gap and one in the lower gap',
});
/**
* The fixed visual identity a playing-card render must preserve. The stable
* roster key is authoritative, so this also repairs renders from older saved
* subject prompts that named the card without spelling out its suit or count.
*/
export function deckCardIdentityPrompt(deck, card) {
if (deck?.kind !== DECK_KIND.PLAYING) return '';
const match = /^(spades|hearts|diamonds|clubs)-(A|[2-9]|10|J|Q|K)$/.exec(String(card?.key || ''));
if (!match) return '';
const [, suitKey, rankKey] = match;
const suit = PLAYING_SUITS.find((entry) => entry.key === suitKey);
const rank = PLAYING_RANKS.find((entry) => entry.key === rankKey);
if (!suit || !rank) return '';
const pip = PLAYING_SUIT_SHAPES[suitKey];
const cardName = `${rank.name} of ${suit.name}`;
const cornerIndex = `Both corner indices show the exact rank ${rankKey} beside one small matching ${suit.symbol} suit mark.`;
if (rankKey === 'A') {
return `Fixed identity: ${cardName}. Show one large ornate ${pip.color} ${pip.noun} emblem (${suit.symbol}), shaped as a ${pip.shape}, in the center; do not repeat it as a pip field. ${cornerIndex} Apart from that emblem and the two corner marks, no other ${pip.noun} shapes appear anywhere. Show no other suit.`;
}
if (/^\d+$/.test(rankKey)) {
const total = Number(rankKey) + 2;
return `Fixed identity: ${cardName}. Exactly ${rankKey} large ${pip.color} ${pip.noun} pips (${suit.symbol}), each a ${pip.shape}, printed flat on the card face in the classic playing-card arrangement: ${PIP_LAYOUTS[rankKey]}. The pips are graphic suit symbols, not objects in the scene; any illustration sits behind or between them and contains no ${pip.noun} shapes. ${cornerIndex} The whole card shows exactly ${total} ${pip.noun} symbols in total (${rankKey} pips plus the 2 corner marks) and no ${pip.noun} motifs in the border, background or scene. Show no other suit.`;
}
return `Fixed identity: ${cardName}. Show one full ${rank.name.toLowerCase()} figure as the central subject, with ${pip.color} ${pip.noun} emblems shaped as a ${pip.shape}. ${cornerIndex} Do not replace the face rank with a numbered pip field or show another suit.`;
}
// Major arcana with the traditional motif each card carries — the prompt
// generator gets these as grounding so a deck stays recognizable as tarot even
// when a universe's cast is placed on the cards.
const MAJOR_ARCANA = Object.freeze([
['The Fool', 'a carefree traveler stepping toward a cliff edge, a small dog at their heels, a white rose in hand'],
['The Magician', 'a figure at a table bearing a cup, a sword, a wand and a coin, one hand raised to the sky, one pointing to the earth'],
['The High Priestess', 'a seated veiled figure between two pillars, a crescent moon at their feet, a scroll in their lap'],
['The Empress', 'a crowned figure enthroned in a lush field of grain and flowing water, a shield bearing a symbol of love'],
['The Emperor', 'a stern crowned ruler on a stone throne carved with rams, a scepter in hand, mountains behind'],
['The Hierophant', 'a robed teacher between two pillars, hand raised in blessing, two acolytes kneeling, crossed keys below'],
['The Lovers', 'two figures beneath a radiant winged presence, a tree of flame and a tree of fruit, a mountain between'],
['The Chariot', 'an armored figure standing in a chariot drawn by two sphinxes, one black and one white, a starry canopy above'],
['Strength', 'a calm figure gently closing the jaws of a lion, an infinity sign above their head, a garland of flowers'],
['The Hermit', 'a cloaked elder on a mountain peak holding a lantern with a six-pointed star, leaning on a staff'],
['Wheel of Fortune', 'a great wheel inscribed with symbols, a sphinx atop it, creatures reading books in the four corners'],
['Justice', 'a crowned figure enthroned holding an upright sword and a set of balanced scales, between two pillars'],
['The Hanged Man', 'a serene figure suspended upside down by one foot from a living tree, a halo of light around the head'],
['Death', 'an armored skeletal rider on a pale horse carrying a black banner with a white rose, a sunrise between two towers'],
['Temperance', 'a winged figure with one foot in water and one on land, pouring water between two cups, a path to a distant crown of light'],
['The Devil', 'a horned figure on a black pedestal, two chained figures below, an inverted five-pointed star, a raised torch'],
['The Tower', 'a tower on a crag struck by lightning, its crown toppling, two figures falling, flames from the windows'],
['The Star', 'a kneeling figure pouring water from two vessels onto land and pool beneath one great star and seven smaller stars'],
['The Moon', 'a full moon over a path between two towers, a dog and a wolf howling, a crayfish emerging from a pool'],
['The Sun', 'a radiant sun above a joyful child on a white horse, sunflowers over a garden wall, a red banner'],
['Judgement', 'a winged herald sounding a trumpet from the clouds while figures rise from open graves below, mountains behind'],
['The World', 'a dancing figure wreathed in a laurel oval holding two wands, the four living creatures in the corners'],
]);
const TAROT_SUITS = Object.freeze([
{ key: 'wands', name: 'Wands' },
{ key: 'cups', name: 'Cups' },
{ key: 'swords', name: 'Swords' },
{ key: 'pentacles', name: 'Pentacles' },
]);
const TAROT_RANKS = Object.freeze([
{ key: 'ace', name: 'Ace' }, { key: '2', name: 'Two' }, { key: '3', name: 'Three' },
{ key: '4', name: 'Four' }, { key: '5', name: 'Five' }, { key: '6', name: 'Six' },
{ key: '7', name: 'Seven' }, { key: '8', name: 'Eight' }, { key: '9', name: 'Nine' },
{ key: '10', name: 'Ten' }, { key: 'page', name: 'Page' }, { key: 'knight', name: 'Knight' },
{ key: 'queen', name: 'Queen' }, { key: 'king', name: 'King' },
]);
const ROMAN = ['0', 'I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX', 'X', 'XI', 'XII', 'XIII', 'XIV', 'XV', 'XVI', 'XVII', 'XVIII', 'XIX', 'XX', 'XXI'];
const backCard = () => ({
key: DECK_BACK_KEY,
name: 'Card back',
group: 'back',
groupLabel: 'Back',
rank: null,
motif: 'the shared reverse-side pattern every card in the deck carries — a repeating symmetrical emblem, no figures, no text',
});
function playingRoster() {
const cards = [];
for (const suit of PLAYING_SUITS) {
for (const rank of PLAYING_RANKS) {
cards.push({
key: `${suit.key}-${rank.key}`,
name: `${rank.name} of ${suit.name}`,
group: suit.key,
groupLabel: suit.name,
rank: rank.key,
motif: null,
});
}
}
cards.push({ key: 'joker-1', name: 'Joker (red)', group: 'jokers', groupLabel: 'Jokers', rank: 'joker', motif: 'a jester figure in the deck\'s world' });
cards.push({ key: 'joker-2', name: 'Joker (black)', group: 'jokers', groupLabel: 'Jokers', rank: 'joker', motif: 'a second, contrasting jester figure' });
cards.push(backCard());
return cards;
}
function tarotRoster() {
const cards = MAJOR_ARCANA.map(([name, motif], i) => ({
key: `major-${i}`,
name: `${ROMAN[i]} · ${name}`,
group: 'major',
groupLabel: 'Major Arcana',
rank: ROMAN[i],
motif,
}));
for (const suit of TAROT_SUITS) {
for (const rank of TAROT_RANKS) {
cards.push({
key: `${suit.key}-${rank.key}`,
name: `${rank.name} of ${suit.name}`,
group: suit.key,
groupLabel: suit.name,
rank: rank.key,
motif: null,
});
}
}
cards.push(backCard());
return cards;
}
/**
* The card roster a deck of `kind` mints on creation, in display order. Each
* entry is `{ key, name, group, groupLabel, rank, motif }` — `key` is the
* stable per-deck slot identity (`hearts-Q`, `major-17`, `back`).
*/
export function deckCardRoster(kind) {
if (kind === DECK_KIND.PLAYING) return playingRoster();
if (kind === DECK_KIND.TAROT) return tarotRoster();
throw new Error(`Unknown deck kind: ${kind}`);
}
/**
* Compose the prompt one card renders with. Order is deliberate: the deck's
* embrace influences lead (diffusion models weight early tokens heaviest),
* then the shared layout clause, then the card's own subject. The avoid list
* becomes the negative prompt, after any per-card negative.
*
* `parts` carries the same clauses unjoined, so the card editor can show
* which contribution came from the deck (style, layout, avoid list) and which
* from the card itself — a composed blob alone leaves the user unable to tell
* why a render picked up wording they never typed.
*/
export function composeCardRenderPrompt(deck, card) {
// A deck carries the same `influences` shape a universe does, so the
// universe's visual-style projection is the one definition of "what the
// embrace/avoid lists contribute to an image prompt".
const style = buildVisualStyleClause(deck);
const avoid = universeVisualStyleTokens(deck).avoid.join(', ');
const layout = trimmed(deck?.layoutPrompt);
const orientation = deckCardOrientationPrompt(deck);
const orientationNegative = deckCardOrientationNegativePrompt(deck);
const identity = deckCardIdentityPrompt(deck, card);
const subject = identity
? [identity, trimmed(card?.prompt)].filter(Boolean).join(' ')
: [trimmed(card?.name), trimmed(card?.prompt)].filter(Boolean).join(': ');
const body = [layout, orientation, subject].filter(Boolean).join('. ');
const identityNegative = identity ? 'wrong card rank, wrong card suit, incorrect pip count, missing pips, extra pips, extra suit symbols, suit symbols in the border or background, pips disguised as scene objects' : '';
const cardNegative = [trimmed(card?.negativePrompt), orientationNegative, identityNegative].filter(Boolean).join(', ');
const composed = composeStyledPrompt(body, cardNegative, { prompt: style, negativePrompt: avoid });
// The deck's blocks around the card's own words, for the render's sent-prompt
// record (#11317). The card's own negative is the user's text, so it is not one.
const promptAdditions = [
['deck-style', 'Deck style', style],
['deck-layout', 'Deck layout', layout],
['card-orientation', 'Card orientation', orientation],
['card-identity', 'Card identity', identity],
['deck-avoid', 'Deck avoid (negative prompt)', avoid],
['card-orientation-negatives', 'Card orientation negatives', orientationNegative],
['card-identity-negatives', 'Card identity negatives', identityNegative],
].filter(([, , text]) => text).map(([id, label, text]) => ({ id, label, text }));
return { ...composed, promptAdditions, parts: { style, layout, orientation, subject } };
}
const IN_FLIGHT_RENDER = new Set(['queued', 'running']);
/** The media-job id a card is currently waiting on, or null. */
export const cardInFlightJobId = (card) => (
IN_FLIGHT_RENDER.has(card?.render?.status) && card.render.jobId ? card.render.jobId : null
);
/** Derived render state for one card row. */
export function cardStatus(card) {
const render = card?.render || null;
if (render?.status === 'queued') return CARD_STATUS.QUEUED;
if (render?.status === 'running') return CARD_STATUS.RUNNING;
if (Array.isArray(card?.imageRefs) && card.imageRefs.length) return CARD_STATUS.RENDERED;
if (render?.status === 'failed' || render?.status === 'canceled') return CARD_STATUS.FAILED;
return trimmed(card?.prompt) ? CARD_STATUS.PROMPTED : CARD_STATUS.EMPTY;
}
/** Completion counters for a deck's card list. */
export function deckCompletion(cards) {
const list = Array.isArray(cards) ? cards : [];
const counts = { total: list.length, prompted: 0, rendered: 0, inFlight: 0, failed: 0 };
for (const card of list) {
if (trimmed(card?.prompt)) counts.prompted += 1;
const status = cardStatus(card);
if (status === CARD_STATUS.RENDERED) counts.rendered += 1;
else if (status === CARD_STATUS.QUEUED || status === CARD_STATUS.RUNNING) counts.inFlight += 1;
else if (status === CARD_STATUS.FAILED) counts.failed += 1;
}
counts.percent = counts.total ? Math.round((counts.rendered / counts.total) * 100) : 0;
return counts;
}