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
/**
* Storyboard / video shot-continuity deterministic primitives (#1315) for the
* editorial check registry. Pure and dependency-free (no side-effecting imports)
* so it stays unit-testable in isolation — mirrors ./nameSimilarity.js and the
* other deterministic scanners.
*
* Backs the deterministic `visual.shot-continuity` check in checkRegistry.js,
* which reasons over a storyboard scene's `shots[]` (each carrying the
* film-grammar fields `shotType` + `screenDirection` + `continuityFromShotId`
* from server/lib/shotGrammar.js). Two classic film-grammar errors are computable
* from those signals without an LLM:
*
* 1. **180-degree rule (axis reversal).** When shot B chains from an earlier
* shot A (`B.continuityFromShotId === A.id`) — i.e. the author declared the
* two shots a continuous bridge — and the two shots face OPPOSITE screen
* directions (one `left`, one `right`), the subject appears to flip sides
* across the cut. That's an axis jump that disorients the viewer. A
* continuity-linked pair is the high-precision trigger: the link is the
* author's explicit "these are continuous" signal, so a direction flip
* across it is a real error, not a legitimate reverse-angle.
*
* 2. **Shot-type monotony.** A scene whose shots ALL share one framing (every
* shot `medium`, say) reads as flat, slideshow coverage — no establishing
* wide, no punch-in for emphasis. Flagged only when enough shots are
* classified to be confident it's monotony, not a sparse outline.
*
* High-precision by design (favors under-flagging, like the other deterministic
* scanners). Unclassified shots (null `shotType` / `screenDirection`) are treated
* as ABSENT — skipped, never guessed — per the absent-vs-empty rule. The judgment
* cases this can't compute need an LLM: eyeline match ships as the `visual.eyeline-match`
* check (#1466), fed by `summarizeStoryboardShots` below; appearance/prop continuity
* is a tracked follow-up.
*/
// Two directions are an axis reversal only when both are decided AND opposite.
// `neutral` (head-on / ambiguous) has no axis to cross, so it never reverses.
function isAxisReversal(a, b) {
if (a == null || b == null) return false;
if (a === 'neutral' || b === 'neutral') return false;
return a !== b; // one 'left', one 'right'
}
// Shots of a scene as a safe array (an older/peer-synced scene may carry a
// non-array `shots`). Each element is passed through untouched — the caller
// type-guards the fields it reads.
function sceneShots(scene) {
return Array.isArray(scene?.shots) ? scene.shots : [];
}
/**
* Detect 180-degree-rule axis reversals across continuity-linked shot pairs in
* one scene. For every shot that chains from an earlier shot in the same scene,
* compare their `screenDirection`; a decided-and-opposite pair is flagged.
*
* @param {object} scene a storyboard scene with `shots[]`
* @returns {Array<{ fromId, toId, fromDirection, toDirection, fromDescription, toDescription }>}
*/
export function findAxisReversals(scene) {
const shots = sceneShots(scene);
if (shots.length < 2) return [];
// Shot ids are unique on the extract path (sanitizeShot synthesizes them) but
// the route doesn't enforce cross-shot uniqueness, so a hand-edited scene could
// carry a duplicate id — last-wins here, matching how a continuity ref would
// resolve anyway. Acceptable under the check's high-precision / under-flag design.
const byId = new Map();
for (const s of shots) {
if (s && typeof s === 'object' && typeof s.id === 'string' && s.id) byId.set(s.id, s);
}
const out = [];
for (const shot of shots) {
if (!shot || typeof shot !== 'object') continue;
const fromId = typeof shot.continuityFromShotId === 'string' ? shot.continuityFromShotId : null;
if (!fromId) continue;
const prior = byId.get(fromId);
if (!prior || prior === shot) continue;
const fromDir = typeof prior.screenDirection === 'string' ? prior.screenDirection : null;
const toDir = typeof shot.screenDirection === 'string' ? shot.screenDirection : null;
if (!isAxisReversal(fromDir, toDir)) continue;
out.push({
fromId,
toId: typeof shot.id === 'string' ? shot.id : '',
fromDirection: fromDir,
toDirection: toDir,
fromDescription: typeof prior.description === 'string' ? prior.description : '',
toDescription: typeof shot.description === 'string' ? shot.description : '',
});
}
return out;
}
// Human-readable label for a shot's screen direction, used when rendering shots
// for the LLM eyeline/appearance continuity passes (#1466). The field records the
// side the subject "faces / moves" (shotGrammar.js) — NOT specifically gaze — so
// the label stays neutral ("screen direction: left") rather than asserting the
// subject is LOOKING that way; conflating motion with gaze would induce false
// eyeline contradictions for a shot like "walks left while looking back right".
// `neutral` is head-on; an unset direction is named so the model knows the signal
// is absent, not "left".
const DIRECTION_PROMPT_LABEL = {
left: 'screen direction: left',
right: 'screen direction: right',
neutral: 'screen direction: neutral (head-on)',
};
// Bounds on a single eyeline pass so a very large storyboard can't overflow the
// provider context in one unchunked LLM call. Three independent limits — the pass
// stops at whichever it hits first, and every omission is surfaced in the block
// (NOT silent) so the model and any reader know coverage stopped. An eyeline match
// is a WITHIN-scene judgment, so omitting a scene loses no cross-scene context;
// a future iteration could page across the overflow.
// - EYELINE_MAX_SCENES — most scenes rendered in one pass.
// - EYELINE_MAX_CHARS — total rendered-block character budget (the real
// overflow guard: bounds 60 dense scenes, not just 60).
// Enforced as a HARD ceiling — a single block is
// truncated to the remaining budget if it would exceed it,
// so even one scene with thousands of shots can't blow past.
// - EYELINE_MAX_DESC_CHARS — per-shot description truncation, so one giant shot
// description can't blow the budget on its own.
// - EYELINE_MAX_SHOTS_PER_SCENE — most shot lines rendered per scene (the common
// "deep scene" guard, applied before the char ceiling).
export const EYELINE_MAX_SCENES = 60;
export const EYELINE_MAX_CHARS = 24_000;
export const EYELINE_MAX_DESC_CHARS = 600;
export const EYELINE_MAX_SHOTS_PER_SCENE = 40;
/**
* Render the collected storyboard scenes into a compact, ordered text block for
* an LLM continuity pass (eyeline match — #1466 — and, later, appearance/prop
* continuity). Pure + deterministic so it's unit-testable and so its token cost
* is countable. Each qualifying scene becomes a labeled block; each shot is one
* line carrying the fields the model reasons over: id, shot type, screen
* direction, continuity link, and the free-text description (the eyeline signal).
*
* A scene qualifies only when it has at least two shots with a non-empty
* description — an eyeline/appearance match is a judgment ACROSS shots, so a
* single-shot (or description-less) scene has nothing to compare. ALL shots of a
* qualifying scene are rendered (not just the described ones) so a
* `continuityFromShotId` reference still resolves to a visible line; an
* undescribed shot renders its description as `(no description)`.
*
* The rendered payload is bounded four ways (scene count, shots-per-scene, total
* chars, per-shot description length — see the EYELINE_MAX_* constants) so one
* unchunked LLM call can't overflow the provider context whether the storyboard
* is wide (many scenes), deep (a few enormous descriptions), or has one pathological
* scene with thousands of shots. The total-char budget is a HARD ceiling: a block
* that would exceed the remaining budget is truncated to it, so the returned string
* never exceeds `maxChars` (plus the two short trailing markers). When anything is
* dropped or truncated a trailing marker says so — the truncation is never silent.
*
* Returns '' when no scene qualifies, so the caller can gate the LLM call on a
* non-empty block (mirrors the object-backstory check's row gate).
*
* @param {Array<{ issueNumber: number|null, scene: object }>} storyboardScenes
* @param {{ maxScenes?: number, maxChars?: number, maxDescChars?: number, maxShotsPerScene?: number }} [opts]
* @returns {string}
*/
export function summarizeStoryboardShots(storyboardScenes, opts = {}) {
const maxScenes = Number.isInteger(opts.maxScenes) && opts.maxScenes > 0
? opts.maxScenes
: EYELINE_MAX_SCENES;
const maxChars = Number.isInteger(opts.maxChars) && opts.maxChars > 0
? opts.maxChars
: EYELINE_MAX_CHARS;
const maxDescChars = Number.isInteger(opts.maxDescChars) && opts.maxDescChars > 0
? opts.maxDescChars
: EYELINE_MAX_DESC_CHARS;
const maxShotsPerScene = Number.isInteger(opts.maxShotsPerScene) && opts.maxShotsPerScene > 0
? opts.maxShotsPerScene
: EYELINE_MAX_SHOTS_PER_SCENE;
const entries = Array.isArray(storyboardScenes) ? storyboardScenes : [];
const blocks = [];
let qualifying = 0;
let usedChars = 0;
let truncatedDesc = false;
let truncatedShots = false;
let truncatedBlock = false;
for (const entry of entries) {
const scene = entry?.scene;
if (!scene || typeof scene !== 'object') continue;
const shots = sceneShots(scene);
const describedCount = shots.filter(
(s) => s && typeof s === 'object' && typeof s.description === 'string' && s.description.trim(),
).length;
// Need at least two described shots to compare an eyeline / appearance across.
if (describedCount < 2) continue;
qualifying += 1;
// Keep counting (for the omission marker) but stop rendering once EITHER the
// scene cap or the character budget is reached.
if (blocks.length >= maxScenes || usedChars >= maxChars) continue;
const issueNumber = Number.isInteger(entry.issueNumber) ? entry.issueNumber : null;
const sceneName = typeof scene.heading === 'string' && scene.heading.trim()
? scene.heading.trim()
: (typeof scene.slugline === 'string' && scene.slugline.trim() ? scene.slugline.trim() : 'scene');
const header = issueNumber != null
? `Scene ${blocks.length + 1} (Issue ${issueNumber}): ${sceneName}`
: `Scene ${blocks.length + 1}: ${sceneName}`;
const lines = [];
let renderedShots = 0;
for (const s of shots) {
if (!s || typeof s !== 'object') continue;
// Bound shots-per-scene so one pathological scene with thousands of shots
// can't dominate the pass; the dropped tail is reported in the line below.
if (renderedShots >= maxShotsPerScene) { truncatedShots = true; break; }
const id = typeof s.id === 'string' && s.id ? s.id : 'shot';
const type = typeof s.shotType === 'string' && s.shotType ? s.shotType : 'unspecified framing';
const dir = DIRECTION_PROMPT_LABEL[s.screenDirection] || 'screen direction unspecified';
const from = typeof s.continuityFromShotId === 'string' && s.continuityFromShotId
? ` (continues from ${s.continuityFromShotId})`
: '';
let desc = typeof s.description === 'string' && s.description.trim()
? s.description.trim()
: '(no description)';
if (desc.length > maxDescChars) {
desc = `${desc.slice(0, maxDescChars)}…[truncated]`;
truncatedDesc = true;
}
lines.push(` - ${id} [${type}, ${dir}]${from}: ${desc}`);
renderedShots += 1;
}
if (truncatedShots && renderedShots === maxShotsPerScene) {
lines.push(' - …[further shots in this scene omitted to fit the model context]');
}
let block = `${header}\n${lines.join('\n')}`;
// HARD char ceiling: even after the per-shot and per-scene caps, truncate the
// assembled block to whatever budget remains so the total can't be exceeded by
// a single scene. Reserve the join's 2 chars.
const remaining = maxChars - usedChars - 2;
if (block.length > remaining) {
block = `${block.slice(0, Math.max(0, remaining))}…[scene truncated]`;
truncatedBlock = true;
}
blocks.push(block);
usedChars += block.length + 2; // +2 for the '\n\n' join that will follow
}
if (!blocks.length) return '';
const omitted = qualifying - blocks.length;
if (omitted > 0) {
blocks.push(`(${omitted} additional scene${omitted === 1 ? '' : 's'} omitted from this eyeline pass to fit the model context — review them in a later pass.)`);
}
if (truncatedDesc || truncatedShots || truncatedBlock) {
blocks.push('(Some shots or descriptions were truncated to fit the model context — open the storyboard for the full text.)');
}
return blocks.join('\n\n');
}
/**
* Detect shot-type monotony in one scene: enough classified shots that they ALL
* share a single `shotType`. Returns the monotony descriptor or null.
*
* Only CLASSIFIED shots (non-null `shotType`) count toward the verdict — an
* outline where the extractor tagged framing on some shots but not others isn't
* penalized for the untagged ones. The scene is flagged only when at least
* `minClassified` shots are classified AND every classified one is the same type
* (so a 2-of-5 partial tag never trips it).
*
* @param {object} scene
* @param {{ minClassified?: number }} [opts] minClassified — floored at 2 (a
* single classified shot is never "monotony"); default 3.
* @returns {{ shotType: string, classifiedCount: number } | null}
*/
export function findShotTypeMonotony(scene, opts = {}) {
const minClassified = Math.max(2, Number.isInteger(opts.minClassified) ? opts.minClassified : 3);
const shots = sceneShots(scene);
const types = [];
for (const s of shots) {
if (s && typeof s === 'object' && typeof s.shotType === 'string' && s.shotType) types.push(s.shotType);
}
if (types.length < minClassified) return null;
const first = types[0];
if (!types.every((t) => t === first)) return null;
return { shotType: first, classifiedCount: types.length };
}