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 { describe, expect, it } from 'vitest';
import {
STOCK_TEXT_ENCODER_ID,
videoTextEncoderOptions,
videoTextEncoderOption,
isStockTextEncoder,
supportsVideoTextEncoder,
resolveVideoTextEncoder,
downloadableVideoTextEncoders,
downloadableVideoTextEncoder,
publicTextEncoderOption,
videoTextEncoderRuntimes,
declaredVideoTextEncoders,
} from './videoTextEncoders.js';
import { isSafeHfRepoRelativePath } from './hfCache.js';
const H3 = { id: 'minimax_h3_8bit', runtime: 'minimax_h3' };
const LTX = { id: 'ltx2_unified', runtime: 'ltx2' };
const LTX25 = { id: 'ltx25_mlx_q8', runtime: 'ltx25' };
describe('videoTextEncoders', () => {
// An empty list is the signal the client uses to hide the picker entirely, so
// a runtime with nothing to substitute must NOT report its built-in option —
// otherwise every model renders a one-entry select that does nothing.
it('offers nothing for a runtime with no substitutions', () => {
expect(videoTextEncoderOptions(LTX)).toEqual([]);
expect(videoTextEncoderOptions({ runtime: 'wan22' })).toEqual([]);
expect(videoTextEncoderOptions(null)).toEqual([]);
});
it('lists the stock option first for a runtime that has substitutions', () => {
const options = videoTextEncoderOptions(H3);
expect(options.length).toBeGreaterThan(1);
expect(options[0].id).toBe(STOCK_TEXT_ENCODER_ID);
expect(options[0].builtIn).toBe(true);
expect(options.slice(1).every((option) => !option.builtIn)).toBe(true);
});
// The client selects options[0] by default, so a runtime whose list did not
// lead with its built-in entry would silently start every render on a
// substitute. Asserted across EVERY runtime rather than the one the tests
// above happen to name, so a second table key can't ship mis-ordered.
it('leads every runtime with exactly one built-in option', () => {
const runtimes = videoTextEncoderRuntimes();
expect(runtimes).toContain('minimax_h3');
expect(runtimes).toContain('ltx25');
for (const runtime of runtimes) {
const options = videoTextEncoderOptions({ runtime });
expect(options[0]).toMatchObject({ id: STOCK_TEXT_ENCODER_ID, builtIn: true });
expect(options.filter((option) => option.builtIn)).toHaveLength(1);
}
});
// Each runtime's built-in entry names ITS conditioner — the picker's default
// row would otherwise tell an LTX-2.5 user their prompt runs through H3's
// Qwen tower.
it('describes each runtime built-in as its own packed conditioner', () => {
expect(videoTextEncoderOption(H3, STOCK_TEXT_ENCODER_ID).label).toMatch(/Qwen3-VL/);
expect(videoTextEncoderOption(LTX25, STOCK_TEXT_ENCODER_ID).label).toMatch(/Gemma 4/);
});
// Absence and the stock sentinel have to mean the same thing everywhere: the
// route drops the sentinel from persisted params, so a resumed render sends
// absence where the original sent 'stock'.
it.each([undefined, null, '', STOCK_TEXT_ENCODER_ID])('treats %j as no override', (id) => {
expect(isStockTextEncoder(id)).toBe(true);
expect(resolveVideoTextEncoder(H3, id)).toBeNull();
// Even on a runtime that offers no substitutions at all.
expect(resolveVideoTextEncoder(LTX, id)).toBeNull();
});
it('resolves a substitute with the loader mechanics the runner needs', () => {
const option = resolveVideoTextEncoder(H3, 'heretic-bf16');
expect(option.repo).toBeTruthy();
// A floating revision would let the upstream repo change the weights under
// a pinned PortOS build.
expect(option.revision).toMatch(/^[0-9a-f]{40}$/);
expect(option.files).toEqual([expect.stringMatching(/\.safetensors$/)]);
expect(Object.keys(option.keyPrefixMap).length).toBeGreaterThan(0);
});
// An upstream checkpoint arrives as several shards; the ones holding only
// language layers past the conditioning depth are deliberately not pinned, so
// the list is a subset of the repo rather than every shard it publishes.
it('resolves a multi-shard substitute with no loader adapters', () => {
const option = resolveVideoTextEncoder(H3, 'huihui-abliterated');
expect(option.revision).toMatch(/^[0-9a-f]{40}$/);
expect(option.files.length).toBeGreaterThan(1);
expect(option.files.every((name) => name.endsWith('.safetensors'))).toBe(true);
// Upstream Hugging Face namespace, and it ships its own final norm — the
// remap and the synthesized norm exist only for a repackaged checkpoint.
expect(option.keyPrefixMap).toBeUndefined();
expect(option.finalNormKey).toBeUndefined();
});
// The remap has to land on the namespace the pinned MLX loader matches
// (`model.language_model.` / `model.visual.`), or every tensor is skipped and
// the load fails with "missing N tensors" after reading ~48 GB.
it('maps the ComfyUI namespace onto the loader namespace', () => {
const { keyPrefixMap } = resolveVideoTextEncoder(H3, 'heretic-bf16');
expect(keyPrefixMap['model.']).toBe('model.language_model.');
expect(keyPrefixMap['visual.']).toBe('model.visual.');
// Declared in the SUBSTITUTE's own namespace so the map above rewrites it
// like any other key — a post-map name would stay unmapped.
const { finalNormKey } = resolveVideoTextEncoder(H3, 'heretic-bf16');
expect(finalNormKey.startsWith('model.')).toBe(true);
expect(finalNormKey.startsWith('model.language_model.')).toBe(false);
});
// Failed ltx25 gates remain unreachable: not in the
// picker, not accepted by route validation, and not downloadable. Declaring
// a pinned candidate is not permission to spend 11-13 GB on weights a render
// still cannot select.
describe('unverified substitutes', () => {
const UNVERIFIED = [
'ltx25-abliterated-4bit',
'ltx25-heretic-8bit',
'ltx25-ltx-heretic-mxfp8',
];
it('offers ltx25 only its built-in conditioner', () => {
expect(videoTextEncoderOptions(LTX25).map((option) => option.id)).toEqual([STOCK_TEXT_ENCODER_ID]);
});
it.each(UNVERIFIED)('refuses to resolve or download %s', (id) => {
expect(supportsVideoTextEncoder(LTX25, id)).toBe(false);
expect(() => resolveVideoTextEncoder(LTX25, id)).toThrow(/has no text encoder/);
expect(downloadableVideoTextEncoder(id)).toBeNull();
expect(downloadableVideoTextEncoders().map((entry) => entry.id)).not.toContain(id);
});
// "Not yet checked" must not collapse into "fine": the flag is required on
// every substitute and only an explicit `true` opens the gate, so a new
// entry is invisible until someone states a verdict rather than shipping by
// omission.
it('requires every declared substitute to state a verdict', () => {
const declared = declaredVideoTextEncoders();
expect(declared.length).toBeGreaterThan(downloadableVideoTextEncoders().length);
for (const entry of declared) expect(typeof entry.verified).toBe('boolean');
// Everything the two lanes DO expose said `true` — nothing rode in on an
// absent or falsy flag.
const offered = videoTextEncoderRuntimes()
.flatMap((runtime) => videoTextEncoderOptions({ runtime }))
.filter((option) => !option.builtIn)
.concat(downloadableVideoTextEncoders());
for (const entry of offered) expect(entry.verified).toBe(true);
});
// An unverified entry gets no shape checking from the download-lane loop
// below (it isn't in that lane yet), so the pins are enforced here — a
// floating revision or an unsafe path must fail when it is WRITTEN, not
// months later when someone flips the flag.
it('pins every declared substitute whether or not it is offered yet', () => {
for (const entry of declaredVideoTextEncoders()) {
expect(entry.repo).toBeTruthy();
expect(entry.revision).toMatch(/^[0-9a-f]{40}$/);
expect(entry.files.every(isSafeHfRepoRelativePath)).toBe(true);
expect(new Set(entry.files.map((name) => name.split('/').pop())).size)
.toBe(entry.files.length);
expect(entry.sizeBytes).toBeGreaterThan(0);
expect(entry.disclosure?.modelCardUrl).toMatch(/^https:\/\/huggingface\.co\//);
}
});
// The shim reads the substitute's OWN config.json to generate the one it
// writes, so an entry that never pinned it would fail in the runner with a
// missing-file error minutes after the download completed.
it('pins the config.json every ltx25 shim is generated from', () => {
const ltx25 = declaredVideoTextEncoders().filter((entry) => entry.id.startsWith('ltx25-'));
expect(ltx25.length).toBeGreaterThan(0);
for (const entry of ltx25) {
expect(entry.files).toContain('config.json');
expect(entry.files).toContain('model.safetensors.index.json');
expect(entry.files).toContain('tokenizer.json');
}
});
// `configOverrides` corrects the ONE thing a unified checkpoint gets wrong.
// Overriding `text_config` or `quantization` would change how the weights
// are interpreted rather than how they are labelled — group-size drift
// dequantizes to noise — so the field must stay a label fix.
it('limits configOverrides to the model_type label', () => {
for (const entry of declaredVideoTextEncoders()) {
if (!entry.configOverrides) continue;
expect(Object.keys(entry.configOverrides)).toEqual(['model_type']);
expect(entry.configOverrides.model_type).toBe('gemma4');
}
// The text-only export already reports gemma4, so it declares none.
expect(declaredVideoTextEncoders()
.find((entry) => entry.id === 'ltx25-abliterated-4bit').configOverrides).toBeUndefined();
expect(declaredVideoTextEncoders()
.find((entry) => entry.id === 'ltx25-heretic-8bit').configOverrides)
.toEqual({ model_type: 'gemma4' });
expect(declaredVideoTextEncoders()
.find((entry) => entry.id === 'ltx25-ltx-heretic-mxfp8').configOverrides)
.toEqual({ model_type: 'gemma4' });
});
});
// The picker offers a substitute only where its runtime's loader can consume
// it — an id is never global, so H3's conditioners must stay off ltx25 and
// vice versa even once both are verified.
it('keeps a runtime\'s substitutes off the other runtimes', () => {
expect(supportsVideoTextEncoder(LTX25, 'heretic-bf16')).toBe(false);
expect(() => resolveVideoTextEncoder(LTX25, 'heretic-bf16'))
.toThrow(/has no text encoder "heretic-bf16"/);
expect(supportsVideoTextEncoder(H3, 'ltx25-abliterated-4bit')).toBe(false);
});
it('rejects an id the model cannot load', () => {
expect(supportsVideoTextEncoder(H3, 'nope')).toBe(false);
expect(() => resolveVideoTextEncoder(H3, 'nope')).toThrow(/has no text encoder "nope"/);
// The message names what IS available so the caller can correct it.
expect(() => resolveVideoTextEncoder(H3, 'nope')).toThrow(/heretic-bf16/);
});
it('rejects a substitute on a runtime with no remap for it', () => {
expect(supportsVideoTextEncoder(LTX, 'heretic-bf16')).toBe(false);
expect(() => resolveVideoTextEncoder(LTX, 'heretic-bf16'))
.toThrow(/does not support a substitute text encoder/);
});
// A built-in option ships inside the model's weights and has no repo of its
// own, so it must never reach the download lane — that would 404 or, worse,
// try to snapshot a repo that doesn't exist.
it('excludes built-in options from the download lane', () => {
const ids = downloadableVideoTextEncoders().map((entry) => entry.id);
expect(ids).not.toContain(STOCK_TEXT_ENCODER_ID);
expect(ids).toContain('heretic-bf16');
expect(downloadableVideoTextEncoder(STOCK_TEXT_ENCODER_ID)).toBeNull();
expect(downloadableVideoTextEncoder('heretic-bf16')).toBeTruthy();
for (const entry of downloadableVideoTextEncoders()) {
expect(entry.repo).toBeTruthy();
// Always an explicit file list. A snapshot of any of these repos pulls
// quantizations, generation tails or never-built layers the loader can't
// use — tens of GB of waste per entry.
expect(entry.files.length).toBeGreaterThan(0);
// Weights are the point; the companion files an ltx25 shim also pins
// (shard index, tokenizer, generation config) are not weights, so the
// shape rule is "carries weights", not "is nothing but weights".
expect(entry.files.some((name) => name.endsWith('.safetensors'))).toBe(true);
expect(new Set(entry.files).size).toBe(entry.files.length);
// Through the same predicate the download target validates with, so the
// registry can't declare a path the route would then reject at runtime.
expect(entry.files.every(isSafeHfRepoRelativePath)).toBe(true);
// The shim links every shard into one flat directory, so two shards with
// the same basename would collide on one symlink name.
expect(new Set(entry.files.map((name) => name.split('/').pop())).size).toBe(entry.files.length);
}
});
// The client projection must not carry loader mechanics — publishing them
// invites a client-side reimplementation of the remap that can then drift
// from the runner's.
it('keeps loader mechanics off the client projection', () => {
const projected = publicTextEncoderOption(videoTextEncoderOption(H3, 'heretic-bf16'));
expect(projected.keyPrefixMap).toBeUndefined();
expect(projected.finalNormKey).toBeUndefined();
expect(projected.revision).toBeUndefined();
// …while keeping everything the picker renders.
expect(projected).toMatchObject({
id: 'heretic-bf16',
builtIn: false,
label: expect.any(String),
description: expect.any(String),
// The exact published byte count — the picker formats it, so there is no
// second "~N GB" literal that could drift from the real download.
sizeBytes: expect.any(Number),
});
});
it('projects the stock option as built-in with no download of its own', () => {
const projected = publicTextEncoderOption(videoTextEncoderOption(H3, STOCK_TEXT_ENCODER_ID));
expect(projected).toMatchObject({ id: STOCK_TEXT_ENCODER_ID, builtIn: true });
expect(projected.repo).toBeUndefined();
expect(projected.sizeBytes).toBeUndefined();
});
// Size is declared ONCE, as bytes, and the UI formats it. A second GB literal
// (the shape lib/videoDisclosure.js uses for its own entries) would be a
// driftable restatement of the same fact.
it('declares size only as bytes', () => {
for (const entry of downloadableVideoTextEncoders()) {
expect(entry.sizeBytes).toBeGreaterThan(0);
expect(entry.disclosure?.estimatedDownloadGb).toBeUndefined();
}
});
// The licence descriptor is the SHARED one from lib/videoDisclosure.js, not a
// local restatement — a correction to the licence text URL has to reach both
// tables from one edit.
it('reuses the shared license descriptors', async () => {
const { APACHE_2 } = await import('./videoDisclosure.js');
const entry = videoTextEncoderOption(H3, 'heretic-bf16');
expect(entry.disclosure.weightsLicense).toBe(APACHE_2);
});
// A substitute is someone else's tens-of-GB checkpoint, so its provenance
// stays one click away — the picker links the card it declares here.
it('carries a model card on every non-built-in option', () => {
for (const entry of downloadableVideoTextEncoders()) {
expect(entry.disclosure?.modelCardUrl).toMatch(/^https:\/\/huggingface\.co\//);
}
});
});