AI media harness for planning, generating, and editing locally
TypeScript
import { selectedImageGeneratorTemplate } from "./settings";
import { invoke } from "@tauri-apps/api/core";
import { addReferenceImageAssets } from "./referenceImageAssets";
import {
createProjectConfig,
parseProjectConfig,
seedProjectWorkspace,
type CreateProjectInput,
type PendingReferenceImage,
type ProjectConfig,
type ProjectRecord,
type StoredLocation,
} from "./project";
const RECENTS_KEY = "slopus.recent-projects.v1";
const WEB_PROJECTS_KEY = "slopus.web-projects.v1";
const LEGACY_RECENTS_KEY = "polstudio.recent-projects.v1";
const LEGACY_WEB_PROJECTS_KEY = "polstudio.web-projects.v1";
export const isTauri = () => "__TAURI_INTERNALS__" in window;
/** A project the library knows about but could not read back. */
export interface UnreadableProject {
folderPath: string;
/** The underlying message, kept verbatim so it stays diagnosable. */
detail: string;
}
/** Everything the library loaded, plus everything it failed to load. One bad
* project must never hide the good ones, and it must never vanish silently:
* the Rust validator is looser than the zod schema here, so a config the
* backend happily wrote can still fail to parse on the next launch. */
export interface RecentProjects {
projects: ProjectRecord[];
unreadable: UnreadableProject[];
}
const describeReason = (reason: unknown) => (reason instanceof Error ? reason.message : String(reason));
function readJson<T>(key: string, fallback: T, legacyKey?: string): T {
try {
const current = localStorage.getItem(key);
const value = current ?? (legacyKey ? localStorage.getItem(legacyKey) : null);
if (!current && value) localStorage.setItem(key, value);
return value ? (JSON.parse(value) as T) : fallback;
} catch {
return fallback;
}
}
function rememberPath(path: string): void {
const paths = readJson<string[]>(RECENTS_KEY, [], LEGACY_RECENTS_KEY).filter((item) => item !== path);
localStorage.setItem(RECENTS_KEY, JSON.stringify([path, ...paths].slice(0, 12)));
}
function forgetPath(path: string): void {
const paths = readJson<string[]>(RECENTS_KEY, [], LEGACY_RECENTS_KEY).filter((item) => item !== path);
localStorage.setItem(RECENTS_KEY, JSON.stringify(paths));
}
function webSeedProjects(): ProjectRecord[] {
const now = new Date();
const seeds = [
{
path: "~/Slopus/Northern Light",
prompt: "A cinematic brand film following an architect from sketch to skyline",
name: "Northern Light — Brand Film",
ratio: "16:9" as const,
resolution: "4k" as const,
offset: 12,
},
{
path: "~/Slopus/Field Notes",
prompt: "A warm vertical travel journal through Helsinki's hidden cafés",
name: "Helsinki Field Notes",
ratio: "9:16" as const,
resolution: "1080p" as const,
offset: 46,
},
{
path: "~/Slopus/Aether Launch",
prompt: "A crisp product launch teaser with macro details and kinetic typography",
name: "Aether Product Reveal",
ratio: "16:9" as const,
resolution: "4k" as const,
offset: 130,
},
];
return seeds.map((seed, index) => {
const config = createProjectConfig({
name: seed.name,
prompt: seed.prompt,
aspectRatio: seed.ratio,
resolution: seed.resolution,
targetDurationSeconds: index === 1 ? 30 : 60,
});
config.id = `sample-${index + 1}`;
config.createdAt = new Date(now.getTime() - seed.offset * 86_400_000).toISOString();
config.updatedAt = new Date(now.getTime() - (index * 22 + 3) * 3_600_000).toISOString();
return { folderPath: seed.path, config: seedProjectWorkspace(config, index) };
});
}
function getWebProjects(): RecentProjects {
const stored = readJson<ProjectRecord[] | null>(WEB_PROJECTS_KEY, null, LEGACY_WEB_PROJECTS_KEY);
if (stored) {
const projects: ProjectRecord[] = [];
const unreadable: UnreadableProject[] = [];
for (const record of stored) {
try {
const parsed = parseProjectConfig(record.config);
const sampleIndex = /^sample-(\d+)$/.exec(parsed.id);
projects.push({ ...record, config: sampleIndex ? seedProjectWorkspace(parsed, Number(sampleIndex[1]) - 1) : parsed });
} catch (reason) {
unreadable.push({ folderPath: record.folderPath || "(unknown folder)", detail: describeReason(reason) });
}
}
return { projects, unreadable };
}
const seeded = webSeedProjects();
localStorage.setItem(WEB_PROJECTS_KEY, JSON.stringify(seeded));
return { projects: seeded, unreadable: [] };
}
export async function listRecentProjects(): Promise<RecentProjects> {
if (!isTauri()) return getWebProjects();
const paths = readJson<string[]>(RECENTS_KEY, [], LEGACY_RECENTS_KEY);
const rows = await Promise.all(
paths.map(async (folderPath) => {
try {
const value = await invoke<ProjectRecord>("open_project", { folderPath });
return { ok: true as const, record: { ...value, config: parseProjectConfig(value.config) } };
} catch (reason) {
// Swallowing this made the project disappear from the library with no
// message at all — the worst failure mode in the app. Report it and
// keep every row that did load.
return { ok: false as const, failure: { folderPath, detail: describeReason(reason) } };
}
}),
);
// Heal the stored list from what the backend just resolved. Paths remembered
// by an earlier build carry the Windows verbatim prefix (`\\?\D:\…`), which
// is an OS escape hatch nobody should be shown; every record comes back with
// the ordinary form, so write that back and the list converges on it. A row
// that failed to load keeps its stored path — that string is the one the
// library is actually holding, and the error line has to name it.
const healed = rows.map((row, index) => (row.ok ? row.record.folderPath : paths[index]));
if (healed.some((path, index) => path !== paths[index])) {
localStorage.setItem(RECENTS_KEY, JSON.stringify(healed));
}
return {
projects: rows.flatMap((row) => (row.ok ? [row.record] : [])),
unreadable: rows.flatMap((row) => (row.ok ? [] : [row.failure])),
};
}
export async function chooseAndOpenProject(): Promise<ProjectRecord | null> {
if (!isTauri()) return getWebProjects().projects[0] ?? null;
const value = await invoke<ProjectRecord | null>("choose_project_folder");
if (!value) return null;
const record = { ...value, config: parseProjectConfig(value.config) };
rememberPath(record.folderPath);
return record;
}
export async function chooseInitialReferenceImages(): Promise<PendingReferenceImage[]> {
if (!isTauri()) return [];
return invoke<PendingReferenceImage[]>("choose_initial_reference_images");
}
/** A file the user picked. An IMAGE was copied into the project's `media/`
* folder and comes back as `relativePath`; VIDEO and AUDIO were left where
* they were and come back as an absolute `sourcePath` — a project does not
* duplicate gigabytes of footage to call itself portable. Exactly one of the
* two is set.
*
* No duration or dimensions: Slopus has no decoder yet, and a guessed
* number would be indistinguishable from a measured one downstream. */
export interface ImportedMediaFile {
kind: "video" | "audio" | "image";
name: string;
relativePath: string | null;
sourcePath: string | null;
mimeType: string;
}
/** Opens the picker and adds what was chosen to the project: images copied in,
* video and sound recorded where they already live. Returns an empty list when
* the user cancels — and in the browser, which has no project folder. */
export async function importMediaFiles(folderPath: string): Promise<ImportedMediaFile[]> {
if (!isTauri()) return [];
return invoke<ImportedMediaFile[]>("import_media_files", { folderPath });
}
/** The bytes of one file inside a project folder, as a blob URL the webview
* can point an <img> at. Null in the browser, where there is no folder to
* read from. CALLERS MUST revokeObjectURL when done — a leaked blob URL pins
* the whole image in memory for the life of the document. */
export async function readProjectFileUrl(folderPath: string, relativePath: string, mimeType: string): Promise<string | null> {
if (!isTauri()) return null;
const bytes = await invoke<ArrayBuffer>("read_project_file", { folderPath, relativePath });
return URL.createObjectURL(new Blob([bytes], { type: mimeType }));
}
/** The bytes of an asset or reference wherever it actually is: inside the
* project folder, or at the absolute path the project recorded for it. The
* external read goes through its own command, which only serves paths the
* project itself names — see `read_external_media_file` in
* src-tauri/src/media/access.rs. Same revoke rule as `readProjectFileUrl`. */
export async function readMediaFileUrl(folderPath: string, item: StoredLocation, mimeType: string): Promise<string | null> {
if (!isTauri() || (!item.sourcePath && !item.relativePath)) return null;
return URL.createObjectURL(new Blob([await readMediaFileBytes(folderPath, item)], { type: mimeType }));
}
/** The same read as `readMediaFileUrl`, stopping at the bytes.
*
* The export pipeline wants the file itself — mp4box takes an ArrayBuffer
* apart, and wrapping it in a blob URL first only to fetch it back would copy
* a multi-gigabyte rush for nothing. It exists so that pipeline cannot go and
* read `relativePath` on its own: video and audio have none, and calling
* `read_project_file` with a null relative path dies at IPC argument
* deserialisation before Rust ever sees it — which is exactly the bug this
* sibling was added to end.
*
* Throws rather than returning null: every caller needs the bytes, so an
* absent file is a failure with a reason, not an empty result. */
export async function readMediaFileBytes(folderPath: string, item: StoredLocation): Promise<ArrayBuffer> {
if (!isTauri()) {
throw new Error("Reading project media needs the desktop app; the browser preview has no project folder.");
}
if (item.sourcePath) {
return invoke<ArrayBuffer>("read_external_media_file", { folderPath, sourcePath: item.sourcePath });
}
if (item.relativePath) {
return invoke<ArrayBuffer>("read_project_file", { folderPath, relativePath: item.relativePath });
}
throw new Error("This item records no file at all — neither a path inside the project nor one outside it.");
}
export async function createProject(input: CreateProjectInput): Promise<ProjectRecord | null> {
const config = createProjectConfig(input);
if (config.imageScene) config.imageScene.steps = selectedImageGeneratorTemplate().defaultSteps;
if (isTauri()) {
const value = await invoke<ProjectRecord | null>("create_project", {
projectDirectory: input.projectDirectory ?? null,
config,
initialReferencePaths: input.referenceImages?.map((image) => image.sourcePath) ?? [],
});
if (!value) return null;
const record = { ...value, config: parseProjectConfig(value.config) };
const withImages = addReferenceImageAssets(record.config);
if (withImages !== record.config) return saveProject({ ...record, config: withImages });
rememberPath(record.folderPath);
return record;
}
const slug = input.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
const record = { folderPath: `~/Slopus/${slug || config.id}`, config };
const projects = [record, ...getWebProjects().projects];
localStorage.setItem(WEB_PROJECTS_KEY, JSON.stringify(projects));
return record;
}
export async function saveProject(record: ProjectRecord, protectedPaths: string[] = []): Promise<ProjectRecord> {
const next: ProjectRecord = {
...record,
config: parseProjectConfig({ ...record.config, updatedAt: new Date().toISOString() }),
};
if (isTauri()) {
await invoke("save_project", { folderPath: next.folderPath, config: next.config, ...(protectedPaths.length ? { protectedPaths } : {}) });
} else {
const projects = getWebProjects().projects.filter((project) => project.config.id !== next.config.id);
localStorage.setItem(WEB_PROJECTS_KEY, JSON.stringify([next, ...projects]));
}
rememberPath(next.folderPath);
return next;
}
export interface NewProjectFolder { folderPath: string; error: string | null }
export const chooseNewProjectFolder = () => invoke<NewProjectFolder | null>("choose_new_project_folder");
export const inspectNewProjectFolder = (folderPath: string) => invoke<NewProjectFolder>("inspect_new_project_folder", { folderPath });
/** Permanently removes one confirmed project. The desktop command repeats the
* identity and folder checks at the filesystem boundary before deleting; the
* browser preview removes only its localStorage-backed stand-in. */
export async function deleteProject(record: ProjectRecord): Promise<void> {
if (isTauri()) {
await invoke("delete_project", { folderPath: record.folderPath, projectId: record.config.id });
} else {
const projects = getWebProjects().projects.filter((project) =>
project.config.id !== record.config.id || project.folderPath !== record.folderPath);
localStorage.setItem(WEB_PROJECTS_KEY, JSON.stringify(projects));
}
forgetPath(record.folderPath);
}