Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Keep video and audio where they are, and stop showing verbatim paths

Bittiae88bcfea79c
diff --git a/fixtures/project-v1-external-media.json b/fixtures/project-v1-external-media.json
new file mode 100644
index 0000000..825f4fd
--- /dev/null
+++ b/fixtures/project-v1-external-media.json
@@ -0,0 +1,154 @@
+{
+ "schemaVersion": 1,
+ "id": "project-external-media",
+ "name": "Project with media left where it lives",
+ "createdAt": "2026-01-01T00:00:00.000Z",
+ "updatedAt": "2026-01-01T00:00:00.000Z",
+ "thumbnail": null,
+ "settings": {
+ "aspectRatio": "16:9",
+ "resolution": "1080p",
+ "frameRate": 30,
+ "backgroundColor": "#10131a"
+ },
+ "brief": {
+ "prompt": "a rocket launch over the ocean at dawn",
+ "status": "draft",
+ "targetDurationSeconds": 60,
+ "aspectRatio": "16:9",
+ "resolution": "1080p"
+ },
+ "assets": [
+ {
+ "id": "asset-external-video",
+ "kind": "video",
+ "name": "News broadcast",
+ "sourcePath": "D:\\tmp\\news\\News broadcast\\rush-01.mp4",
+ "mimeType": "video/mp4",
+ "durationMs": 12000,
+ "width": 3840,
+ "height": 2160,
+ "createdAt": "2026-01-01T00:00:00.000Z"
+ },
+ {
+ "id": "asset-external-audio",
+ "kind": "audio",
+ "name": "Room tone",
+ "sourcePath": "/home/nn/Recordings/room tone.wav",
+ "mimeType": "audio/wav",
+ "createdAt": "2026-01-01T00:00:00.000Z"
+ },
+ {
+ "id": "asset-copied-image",
+ "kind": "image",
+ "name": "Title card",
+ "relativePath": "media/title-card.png",
+ "mimeType": "image/png",
+ "width": 1920,
+ "height": 1080,
+ "createdAt": "2026-01-01T00:00:00.000Z"
+ }
+ ],
+ "timeline": {
+ "tracks": [
+ {
+ "id": "track-overlay",
+ "kind": "video",
+ "name": "Overlays",
+ "locked": false,
+ "muted": false,
+ "clips": []
+ },
+ {
+ "id": "track-story",
+ "kind": "video",
+ "name": "Story",
+ "locked": false,
+ "muted": false,
+ "clips": [
+ {
+ "id": "clip-external",
+ "assetId": "asset-external-video",
+ "trackId": "track-story",
+ "startMs": 0,
+ "durationMs": 12000,
+ "sourceStartMs": 0,
+ "label": "01 - Broadcast rush",
+ "status": "approved"
+ }
+ ]
+ },
+ {
+ "id": "track-b-roll",
+ "kind": "video",
+ "name": "B-roll",
+ "locked": false,
+ "muted": false,
+ "clips": []
+ },
+ {
+ "id": "track-voice-over",
+ "kind": "audio",
+ "name": "Voice-over",
+ "locked": false,
+ "muted": false,
+ "clips": []
+ },
+ {
+ "id": "track-music",
+ "kind": "audio",
+ "name": "Music",
+ "locked": false,
+ "muted": false,
+ "clips": []
+ }
+ ]
+ },
+ "references": [
+ {
+ "id": "ref-copied-image",
+ "kind": "image",
+ "name": "Harbor facade",
+ "description": "",
+ "content": null,
+ "relativePath": "references/harbor facade.png",
+ "intendedUse": [
+ "style"
+ ],
+ "createdAt": "2026-01-01T00:00:00.000Z"
+ },
+ {
+ "id": "ref-external-video",
+ "kind": "video",
+ "name": "Reference cut",
+ "description": "",
+ "content": null,
+ "relativePath": null,
+ "sourcePath": "\\\\studio-nas\\shared\\reference cut.mov",
+ "intendedUse": [
+ "style"
+ ],
+ "createdAt": "2026-01-01T00:00:00.000Z"
+ }
+ ],
+ "generationJobs": [
+ {
+ "id": "job-initial-brief",
+ "title": "First scene",
+ "prompt": "a rocket launch over the ocean at dawn",
+ "status": "draft",
+ "stage": "queued",
+ "progress": 0,
+ "providerId": "minimax-h3",
+ "creativeBrief": "a rocket launch over the ocean at dawn",
+ "compiledPrompt": "integrated_multimodal_description: [Shot 1] Live-action, cinematic, a rocket launch over the ocean at dawn\n\noverall_soundscape: The ambient sound and physical action sounds are those the scene and actions described above naturally produce. Nothing beyond what that description already establishes is added.\n\nnon_diegetic_music: N/A",
+ "referenceIds": [],
+ "createdAt": "2026-01-01T00:00:00.000Z",
+ "updatedAt": "2026-01-01T00:00:00.000Z"
+ }
+ ],
+ "agentConversation": {
+ "messages": []
+ },
+ "providerSettings": {}
+}
diff --git a/fixtures/rust-serialized-external-media.json b/fixtures/rust-serialized-external-media.json
new file mode 100644
index 0000000..628a840
--- /dev/null
+++ b/fixtures/rust-serialized-external-media.json
@@ -0,0 +1,156 @@
+{
+ "schemaVersion": 1,
+ "id": "project-external-media",
+ "name": "Project with media left where it lives",
+ "createdAt": "2026-01-01T00:00:00.000Z",
+ "updatedAt": "2026-01-01T00:00:00.000Z",
+ "thumbnail": null,
+ "settings": {
+ "aspectRatio": "16:9",
+ "resolution": "1080p",
+ "frameRate": 30,
+ "backgroundColor": "#10131a"
+ },
+ "brief": {
+ "prompt": "a rocket launch over the ocean at dawn",
+ "status": "draft",
+ "targetDurationSeconds": 60,
+ "aspectRatio": "16:9",
+ "resolution": "1080p"
+ },
+ "assets": [
+ {
+ "id": "asset-external-video",
+ "kind": "video",
+ "name": "News broadcast",
+ "sourcePath": "D:\\tmp\\news\\News broadcast\\rush-01.mp4",
+ "mimeType": "video/mp4",
+ "durationMs": 12000,
+ "width": 3840,
+ "height": 2160,
+ "createdAt": "2026-01-01T00:00:00.000Z"
+ },
+ {
+ "id": "asset-external-audio",
+ "kind": "audio",
+ "name": "Room tone",
+ "sourcePath": "/home/nn/Recordings/room tone.wav",
+ "mimeType": "audio/wav",
+ "createdAt": "2026-01-01T00:00:00.000Z"
+ },
+ {
+ "id": "asset-copied-image",
+ "kind": "image",
+ "name": "Title card",
+ "relativePath": "media/title-card.png",
+ "mimeType": "image/png",
+ "width": 1920,
+ "height": 1080,
+ "createdAt": "2026-01-01T00:00:00.000Z"
+ }
+ ],
+ "timeline": {
+ "tracks": [
+ {
+ "id": "track-overlay",
+ "kind": "video",
+ "name": "Overlays",
+ "locked": false,
+ "muted": false,
+ "clips": []
+ },
+ {
+ "id": "track-story",
+ "kind": "video",
+ "name": "Story",
+ "locked": false,
+ "muted": false,
+ "clips": [
+ {
+ "id": "clip-external",
+ "assetId": "asset-external-video",
+ "trackId": "track-story",
+ "startMs": 0,
+ "durationMs": 12000,
+ "sourceStartMs": 0,
+ "label": "01 - Broadcast rush",
+ "status": "approved"
+ }
+ ]
+ },
+ {
+ "id": "track-b-roll",
+ "kind": "video",
+ "name": "B-roll",
+ "locked": false,
+ "muted": false,
+ "clips": []
+ },
+ {
+ "id": "track-voice-over",
+ "kind": "audio",
+ "name": "Voice-over",
+ "locked": false,
+ "muted": false,
+ "clips": []
+ },
+ {
+ "id": "track-music",
+ "kind": "audio",
+ "name": "Music",
+ "locked": false,
+ "muted": false,
+ "clips": []
+ }
+ ]
+ },
+ "references": [
+ {
+ "id": "ref-copied-image",
+ "kind": "image",
+ "name": "Harbor facade",
+ "description": "",
+ "content": null,
+ "relativePath": "references/harbor facade.png",
+ "intendedUse": [
+ "style"
+ ],
+ "createdAt": "2026-01-01T00:00:00.000Z"
+ },
+ {
+ "id": "ref-external-video",
+ "kind": "video",
+ "name": "Reference cut",
+ "description": "",
+ "content": null,
+ "relativePath": null,
+ "sourcePath": "\\\\studio-nas\\shared\\reference cut.mov",
+ "intendedUse": [
+ "style"
+ ],
+ "createdAt": "2026-01-01T00:00:00.000Z"
+ }
+ ],
+ "generationJobs": [
+ {
+ "id": "job-initial-brief",
+ "title": "First scene",
+ "prompt": "a rocket launch over the ocean at dawn",
+ "status": "draft",
+ "stage": "queued",
+ "progress": 0.0,
+ "providerId": "minimax-h3",
+ "creativeBrief": "a rocket launch over the ocean at dawn",
+ "compiledPrompt": "integrated_multimodal_description: [Shot 1] Live-action, cinematic, a rocket launch over the ocean at dawn\n\noverall_soundscape: The ambient sound and physical action sounds are those the scene and actions described above naturally produce. Nothing beyond what that description already establishes is added.\n\nnon_diegetic_music: N/A",
+ "referenceIds": [],
+ "outputRelativePath": null,
+ "error": null,
+ "createdAt": "2026-01-01T00:00:00.000Z",
+ "updatedAt": "2026-01-01T00:00:00.000Z"
+ }
+ ],
+ "agentConversation": {
+ "messages": []
+ },
+ "providerSettings": {}
+}
diff --git a/src-tauri/src/agent.rs b/src-tauri/src/agent.rs
index 10160cc..8833b2d 100644
--- a/src-tauri/src/agent.rs
+++ b/src-tauri/src/agent.rs
@@ -1,6 +1,6 @@
use crate::{
read_project, validate_and_normalize_config, write_project, AgentMessage, ProjectConfig,
- ProjectRecord, ProviderSetting, LEGACY_PROJECT_FILE_NAME, PROJECT_FILE_NAME,
+ ProjectRecord, ProviderSetting, LEGACY_PROJECT_FILE_NAMES, PROJECT_FILE_NAME,
};
use serde::{Deserialize, Serialize};
use serde_json::Value;
@@ -349,10 +349,11 @@ fn confined_project_root(folder: &Path) -> Result<PathBuf, String> {
let canonical = folder
.canonicalize()
.map_err(|error| format!("Could not resolve project root: {error}"))?;
- if !canonical.is_dir()
- || !(canonical.join(PROJECT_FILE_NAME).is_file()
- || canonical.join(LEGACY_PROJECT_FILE_NAME).is_file())
- {
+ let holds_a_project = canonical.join(PROJECT_FILE_NAME).is_file()
+ || LEGACY_PROJECT_FILE_NAMES
+ .iter()
+ .any(|name| canonical.join(name).is_file());
+ if !canonical.is_dir() || !holds_a_project {
return Err("Agent turns require a valid PolStudio project root.".into());
}
Ok(canonical)
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 4a5df1d..5464057 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -11,10 +11,11 @@ use tauri_plugin_dialog::DialogExt;
mod agent;
mod vidfab;
-const PROJECT_FILE_NAME: &str = "pols.json";
-/// What the file was called before. Folders written by earlier builds still
-/// open; the next save writes `pols.json` and leaves the old file alone.
-const LEGACY_PROJECT_FILE_NAME: &str = "polstudio.project.json";
+const PROJECT_FILE_NAME: &str = "polstudio.json";
+/// What the file was called before, newest first. Folders written by earlier
+/// builds still open; the next save writes `polstudio.json` and leaves the old
+/// file alone, so a project stays readable by the build that made it.
+const LEGACY_PROJECT_FILE_NAMES: [&str; 2] = ["pols.json", "polstudio.project.json"];
const PROJECT_DIRECTORIES: [&str; 6] = [
"media/imported",
"media/generated",
@@ -73,7 +74,15 @@ struct ProjectAsset {
id: String,
kind: String,
name: String,
- relative_path: String,
+ // Exactly one of the two locations. `relativePath` is a file COPIED into
+ // the project folder (images, and anything generated here); `sourcePath` is
+ // an absolute path to a file left where the user already keeps it (video
+ // and audio, which are far too big to duplicate). Both keys are omitted
+ // when absent rather than written as null — see the note on `durationMs`.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ relative_path: Option<String>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ source_path: Option<String>,
mime_type: String,
// zod spells these `.optional()` with no `.nullable()`, so an explicit
// `null` is REJECTED by the frontend parser. The key has to stay absent.
@@ -138,6 +147,10 @@ struct ReusableReference {
content: Option<String>,
#[serde(default)]
relative_path: Option<String>,
+ /// An image reference is copied into `references/`; a video or audio
+ /// reference is not, and points at wherever the user keeps it.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ source_path: Option<String>,
#[serde(default)]
intended_use: Vec<String>,
created_at: String,
@@ -220,15 +233,22 @@ struct ImportedReferenceImage {
mime_type: String,
}
-/// One file copied into the project's `media/` folder. Deliberately carries no
-/// duration or dimensions: PolStudio has no decoder yet, and a made-up number
-/// here would be indistinguishable from a measured one everywhere downstream.
+/// One file the user added to a project. An IMAGE is copied into the project's
+/// `media/` folder and comes back with `relative_path`; VIDEO and AUDIO are
+/// left exactly where they are and come back with an absolute `source_path`,
+/// because copying a rush or a stem doubles gigabytes on disk for no benefit.
+/// Exactly one of the two is ever set.
+///
+/// Deliberately carries no duration or dimensions: PolStudio has no decoder
+/// yet, and a made-up number here would be indistinguishable from a measured
+/// one everywhere downstream.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct ImportedMediaFile {
kind: &'static str,
name: String,
- relative_path: String,
+ relative_path: Option<String>,
+ source_path: Option<String>,
mime_type: String,
}
@@ -271,6 +291,56 @@ fn normalize_project_path(value: &str) -> Result<String, String> {
Ok(normalized.join("/"))
}
+/// The other kind of stored location: a file the project points at but does
+/// NOT contain. Video and audio are never copied — a 40 GB rush is not going to
+/// be duplicated into a project folder — so the project records where the user
+/// already keeps it.
+///
+/// It must be ABSOLUTE, because it is resolved against nothing: no working
+/// directory, no project root. `..` is refused so the recorded string is the
+/// same string every comparison sees; canonicalised paths never contain one.
+/// The separators are left exactly as the OS wrote them. This mirrors
+/// `normalizeExternalPath` in src/lib/project.ts and must keep mirroring it in
+/// both directions.
+fn normalize_external_path(value: &str) -> Result<String, String> {
+ if value.is_empty() || value.contains('\0') {
+ return Err("External media paths cannot be empty or contain null bytes.".into());
+ }
+ let bytes = value.as_bytes();
+ let windows_drive = bytes.len() >= 3
+ && bytes[0].is_ascii_alphabetic()
+ && bytes[1] == b':'
+ && matches!(bytes[2], b'\\' | b'/');
+ if !(windows_drive || value.starts_with("\\\\") || value.starts_with('/')) {
+ return Err(format!(
+ "External media must be recorded as an absolute path, received '{value}'."
+ ));
+ }
+ if value.split(['\\', '/']).any(|component| component == "..") {
+ return Err("External media paths cannot contain '..'.".into());
+ }
+ Ok(value.to_string())
+}
+
+/// Every location a project can hold is one of two things and never both: a
+/// file inside the folder, or a file outside it. `label` names the record so
+/// the message points at the row the user has to fix.
+fn check_one_location(
+ label: &str,
+ relative_path: Option<&String>,
+ source_path: Option<&String>,
+) -> Result<(), String> {
+ match (relative_path, source_path) {
+ (Some(_), Some(_)) => Err(format!(
+ "{label} cannot have both a project-relative path and an external source path."
+ )),
+ (None, None) => Err(format!(
+ "{label} must have either a project-relative path or an external source path."
+ )),
+ _ => Ok(()),
+ }
+}
+
fn is_supported_aspect_ratio(value: &str) -> bool {
matches!(value, "16:9" | "9:16" | "1:1" | "4:5")
}
@@ -475,7 +545,21 @@ fn validate_and_normalize_config(mut config: ProjectConfig) -> Result<ProjectCon
&format!("Asset '{}' createdAt", asset.id),
&asset.created_at,
)?;
- asset.relative_path = normalize_project_path(&asset.relative_path)?;
+ asset.relative_path = asset
+ .relative_path
+ .as_deref()
+ .map(normalize_project_path)
+ .transpose()?;
+ asset.source_path = asset
+ .source_path
+ .as_deref()
+ .map(normalize_external_path)
+ .transpose()?;
+ check_one_location(
+ &format!("Asset '{}'", asset.id),
+ asset.relative_path.as_ref(),
+ asset.source_path.as_ref(),
+ )?;
}
for reference in &mut config.references {
if reference.id.trim().is_empty() || reference.name.trim().is_empty() {
@@ -486,14 +570,34 @@ fn validate_and_normalize_config(mut config: ProjectConfig) -> Result<ProjectCon
.as_deref()
.map(normalize_project_path)
.transpose()?;
+ reference.source_path = reference
+ .source_path
+ .as_deref()
+ .map(normalize_external_path)
+ .transpose()?;
+ if reference.relative_path.is_some() && reference.source_path.is_some() {
+ return Err(format!(
+ "Reference '{}' cannot have both a project-relative path and an external source path.",
+ reference.id
+ ));
+ }
match reference.kind.as_str() {
// A text reference may legitimately be blank: the UI creates one the
// moment "New definition" is clicked, before the user has typed. It
// is marked incomplete there rather than failing the whole save —
// refusing here blocked every unrelated edit in the project.
"text" => {}
- "image" if reference.relative_path.is_some() => {}
- "image" => return Err("Image references require a relative path.".into()),
+ // A file-backed reference has to say where its file is. An image is
+ // copied into `references/`; a video or audio reference is not, and
+ // carries the absolute path of the file the user already has.
+ "image" | "video" | "audio"
+ if reference.relative_path.is_some() || reference.source_path.is_some() => {}
+ "image" => {
+ return Err("Image references require a stored path inside the project.".into())
+ }
+ "video" | "audio" => {
+ return Err("Video and audio references require a source path.".into())
+ }
_ => return Err(format!("Unsupported reference kind '{}'.", reference.kind)),
}
// Absent content is fine; present-but-empty content is not, matching
@@ -703,6 +807,22 @@ fn unique_ids<'a>(
Ok(unique)
}
+/// The settings file to READ from a project folder: the current name if it is
+/// there, otherwise the first legacy name that is. Returns the current name
+/// when the folder holds none of them, so the caller reports a missing
+/// `polstudio.json` rather than a file nobody has written since 2025.
+fn project_file_in(folder: &Path) -> PathBuf {
+ let current = folder.join(PROJECT_FILE_NAME);
+ if current.is_file() {
+ return current;
+ }
+ LEGACY_PROJECT_FILE_NAMES
+ .iter()
+ .map(|name| folder.join(name))
+ .find(|path| path.is_file())
+ .unwrap_or(current)
+}
+
fn read_project(folder: &Path) -> Result<ProjectRecord, String> {
if !folder.is_dir() {
return Err("The selected project folder does not exist.".into());
@@ -710,13 +830,7 @@ fn read_project(folder: &Path) -> Result<ProjectRecord, String> {
let canonical_folder = folder
.canonicalize()
.map_err(|error| format!("Could not resolve project folder: {error}"))?;
- let config_path = canonical_folder.join(PROJECT_FILE_NAME);
- let legacy_path = canonical_folder.join(LEGACY_PROJECT_FILE_NAME);
- let config_path = if !config_path.is_file() && legacy_path.is_file() {
- legacy_path
- } else {
- config_path
- };
+ let config_path = project_file_in(&canonical_folder);
let json = fs::read_to_string(&config_path)
.map_err(|error| format!("Could not read {}: {error}", config_path.to_string_lossy()))?;
let config: ProjectConfig = serde_json::from_str(&json)
@@ -821,17 +935,24 @@ fn atomic_replace(temporary: &Path, destination: &Path) -> io::Result<()> {
}
}
-/// `Path::canonicalize` returns a Windows *verbatim* path — `\?\D:\tmp\news`.
-/// That prefix is an OS-level escape hatch, not something to show anybody, and
-/// it was being rendered verbatim under every project in the library. Strip it
-/// for the path that leaves this process. Every command re-canonicalizes what
-/// it is given, so the stripped form is still a valid round trip.
+/// `Path::canonicalize` returns a Windows *verbatim* path — the real prefix is
+/// four characters, `\\?\`, and the previous version of this function looked
+/// for a three-character `\?\` that no path has ever started with. Nothing was
+/// stripped, so every project in the library rendered as
+/// `\\?\D:\tmp\news\News broadcast`.
+///
+/// Strip it for any path that leaves this process. Every command
+/// re-canonicalizes what it is given, so the stripped form is still a valid
+/// round trip. A verbatim UNC path is `\\?\UNC\server\share`, whose ordinary
+/// form is `\\server\share` — dropping only the `\\?\` would leave the bogus
+/// `UNC\server\share`. Non-Windows paths carry neither prefix and come back
+/// untouched.
fn display_path(path: &Path) -> String {
let text = path.to_string_lossy().into_owned();
- if let Some(rest) = text.strip_prefix(r"\?\UNC\") {
- return format!(r"\{rest}");
+ if let Some(rest) = text.strip_prefix(r"\\?\UNC\") {
+ return format!(r"\\{rest}");
}
- text.strip_prefix(r"\?\").unwrap_or(&text).to_string()
+ text.strip_prefix(r"\\?\").unwrap_or(&text).to_string()
}
fn safe_folder_name(name: &str) -> String {
@@ -975,8 +1096,69 @@ fn choose_reference_image(
copy_reference_image(&source, &project_folder).map(Some)
}
-/// Extensions PolStudio will copy into a project, and what each one is.
-/// Anything not listed is refused rather than imported as an unknown blob.
+/// One reference the user added: an image copied into `references/`, or a
+/// video/audio file left where it is and pointed at.
+#[derive(Debug, Clone)]
+struct ImportedReference {
+ kind: &'static str,
+ name: String,
+ relative_path: Option<String>,
+ source_path: Option<String>,
+}
+
+/// The absolute, prefix-free path this project will remember a file by.
+/// Canonicalised so it survives a working-directory change and so the
+/// containment check in `read_external_media_file` compares like with like,
+/// then run through `display_path` so no `\\?\` ever reaches the project file
+/// or the UI, and finally through the same validator the schema applies.
+fn external_source_path(source: &Path) -> Result<String, String> {
+ let canonical = source
+ .canonicalize()
+ .map_err(|error| format!("Could not resolve {}: {error}", source.to_string_lossy()))?;
+ normalize_external_path(&display_path(&canonical))
+}
+
+/// Adds one file to a project as a reference, following the same rule the media
+/// panel does: pictures are small and get copied so the folder stays portable;
+/// video and audio are not copied at any size.
+fn import_reference_file(
+ source: &Path,
+ project_folder: &Path,
+) -> Result<ImportedReference, String> {
+ if !source.is_file() {
+ return Err("The selected file does not exist.".into());
+ }
+ let extension = source
+ .extension()
+ .and_then(|value| value.to_str())
+ .map(str::to_ascii_lowercase)
+ .unwrap_or_default();
+ match media_kind_and_mime(&extension) {
+ Some(("image", _)) => {
+ let copied = copy_reference_image(source, project_folder)?;
+ Ok(ImportedReference {
+ kind: "image",
+ name: copied.name,
+ relative_path: Some(copied.relative_path),
+ source_path: None,
+ })
+ }
+ Some((kind @ ("video" | "audio"), _)) => Ok(ImportedReference {
+ kind,
+ name: source
+ .file_stem()
+ .and_then(|value| value.to_str())
+ .unwrap_or("Reference")
+ .to_string(),
+ relative_path: None,
+ source_path: Some(external_source_path(source)?),
+ }),
+ _ => Err("Choose an image, a video, or a sound file.".into()),
+ }
+}
+
+/// Extensions PolStudio accepts, and what each one is. Anything not listed is
+/// refused rather than imported as an unknown blob.
fn media_kind_and_mime(extension: &str) -> Option<(&'static str, &'static str)> {
Some(match extension {
"mp4" | "m4v" => ("video", "video/mp4"),
@@ -1001,7 +1183,12 @@ const MEDIA_EXTENSIONS: &[&str] = &[
"jpg", "jpeg", "webp", "gif",
];
-fn copy_media_file(source: &Path, project_folder: &Path) -> Result<ImportedMediaFile, String> {
+/// Adds one file to the project. Video and audio are NEVER copied: a folder of
+/// rushes is tens of gigabytes, and duplicating it to make the project folder
+/// "portable" costs the user that much disk to gain a copy they did not ask
+/// for. The project records where the file already lives instead. Images are
+/// small and stay copied, so a project's own artwork travels with it.
+fn import_media_file(source: &Path, project_folder: &Path) -> Result<ImportedMediaFile, String> {
if !source.is_file() {
return Err(format!("{} does not exist.", source.to_string_lossy()));
}
@@ -1012,6 +1199,19 @@ fn copy_media_file(source: &Path, project_folder: &Path) -> Result<ImportedMedia
.ok_or_else(|| "The selected file needs a file extension.".to_string())?;
let (kind, mime_type) = media_kind_and_mime(&extension)
.ok_or_else(|| format!("PolStudio cannot import .{extension} files yet."))?;
+ if kind != "image" {
+ return Ok(ImportedMediaFile {
+ kind,
+ name: source
+ .file_stem()
+ .and_then(|value| value.to_str())
+ .unwrap_or("Imported media")
+ .to_string(),
+ relative_path: None,
+ source_path: Some(external_source_path(source)?),
+ mime_type: mime_type.into(),
+ });
+ }
let media_folder = project_folder.join("media");
fs::create_dir_all(&media_folder)
.map_err(|error| format!("Could not prepare media folder: {error}"))?;
@@ -1034,7 +1234,8 @@ fn copy_media_file(source: &Path, project_folder: &Path) -> Result<ImportedMedia
Ok(ImportedMediaFile {
kind,
name: display_name.to_string(),
- relative_path: format!("media/{file_name}"),
+ relative_path: Some(format!("media/{file_name}")),
+ source_path: None,
mime_type: mime_type.into(),
})
}
@@ -1043,7 +1244,7 @@ fn copy_media_file(source: &Path, project_folder: &Path) -> Result<ImportedMedia
/// reference image the user imported. Confined to the project folder: the
/// relative path goes through the same normaliser every stored path does, and
/// the result is checked to still sit under the canonical root, so a crafted
-/// `..` in a hand-edited pols.json cannot read the rest of the disk.
+/// `..` in a hand-edited polstudio.json cannot read the rest of the disk.
#[tauri::command]
fn read_project_file(
folder_path: String,
@@ -1064,8 +1265,78 @@ fn read_project_file(
Ok(tauri::ipc::Response::new(bytes))
}
-/// Copies the chosen files into the project so the folder stays portable — the
-/// same rule references already follow. An empty list means the user cancelled.
+/// Every absolute path this project has recorded — the media and references
+/// that live OUTSIDE the folder. It is the allow-list for
+/// `read_external_media_file`: the webview may read a file outside the project
+/// only because the project itself names it.
+fn recorded_external_paths(config: &ProjectConfig) -> Vec<String> {
+ config
+ .assets
+ .iter()
+ .filter_map(|asset| asset.source_path.clone())
+ .chain(
+ config
+ .references
+ .iter()
+ .filter_map(|reference| reference.source_path.clone()),
+ )
+ .collect()
+}
+
+/// The bytes of one file the project points at but does not contain.
+///
+/// Video and audio are no longer copied in, so the webview has to be able to
+/// read them where they are — and that is exactly the shape of an arbitrary
+/// file read, so it is fenced three ways:
+///
+/// 1. The path must appear verbatim (after canonicalising both sides) in the
+/// project file ON DISK, not in whatever the caller passes in. The recorded
+/// paths only get there through the OS picker, which is the user choosing
+/// the file themselves.
+/// 2. It must still carry a media extension PolStudio imports, so even a
+/// hand-edited project file cannot turn this into a reader for keys, wallets
+/// or documents.
+/// 3. It must be a regular file that exists now.
+///
+/// What it deliberately does NOT do is trust the caller's string: an argument
+/// that is not on the recorded list is refused whatever it points at.
+#[tauri::command]
+fn read_external_media_file(
+ folder_path: String,
+ source_path: String,
+) -> Result<tauri::ipc::Response, String> {
+ external_media_bytes(&folder_path, &source_path).map(tauri::ipc::Response::new)
+}
+
+fn external_media_bytes(folder_path: &str, source_path: &str) -> Result<Vec<u8>, String> {
+ let project = read_project(Path::new(&folder_path))?;
+ let requested = PathBuf::from(&source_path)
+ .canonicalize()
+ .map_err(|error| format!("Could not resolve {source_path}: {error}"))?;
+ let recorded = recorded_external_paths(&project.config).into_iter().any(|path| {
+ PathBuf::from(&path)
+ .canonicalize()
+ .map(|canonical| canonical == requested)
+ .unwrap_or(false)
+ });
+ if !recorded {
+ return Err(format!(
+ "{source_path} is not one of the files this project points at."
+ ));
+ }
+ let extension = requested
+ .extension()
+ .and_then(|value| value.to_str())
+ .map(str::to_ascii_lowercase)
+ .unwrap_or_default();
+ if media_kind_and_mime(&extension).is_none() || !requested.is_file() {
+ return Err(format!("{source_path} is not a media file PolStudio reads."));
+ }
+ fs::read(&requested).map_err(|error| format!("Could not read {source_path}: {error}"))
+}
+
+/// Adds the chosen files to the project: images are copied in, video and audio
+/// are recorded where they already are. An empty list means the user cancelled.
#[tauri::command]
fn import_media_files(
app: AppHandle,
@@ -1077,7 +1348,7 @@ fn import_media_files(
let selected = app
.dialog()
.file()
- .set_title("Import media into this project")
+ .set_title("Add media to this project")
.add_filter("Media", MEDIA_EXTENSIONS)
.blocking_pick_files();
let Some(selected) = selected else {
@@ -1089,7 +1360,7 @@ fn import_media_files(
let source = path
.into_path()
.map_err(|error| format!("Could not access the selected file: {error}"))?;
- copy_media_file(&source, &project_folder)
+ import_media_file(&source, &project_folder)
})
.collect()
}
@@ -1153,7 +1424,7 @@ fn create_project_in_with_references(
}
let prepare_result = (|| -> Result<(), String> {
for (index, source) in reference_paths.iter().enumerate() {
- let imported = copy_reference_image(source, &project_folder)?;
+ let imported = import_reference_file(source, &project_folder)?;
let mut reference_id = format!("ref-initial-{}", index + 1);
let mut suffix = 2;
while config
@@ -1166,7 +1437,10 @@ fn create_project_in_with_references(
}
config.references.push(ReusableReference {
id: reference_id.clone(),
- kind: "image".into(),
+ // Whatever the file actually is. A video or sound reference is
+ // recorded by path, not copied, so calling it an image here
+ // would be a claim about a file nobody has looked at.
+ kind: imported.kind.into(),
name: imported.name,
// MUST stay empty. The prompt compiler emits a reference's
// description as the subject's own traits in the text sent to
@@ -1175,7 +1449,8 @@ fn create_project_in_with_references(
// Same hazard the text path documents at src/lib/project.ts:87.
description: String::new(),
content: None,
- relative_path: Some(imported.relative_path),
+ relative_path: imported.relative_path,
+ source_path: imported.source_path,
intended_use: vec!["style".into()],
created_at: config.created_at.clone(),
});
@@ -1322,6 +1597,7 @@ pub fn run() {
choose_reference_image,
import_media_files,
read_project_file,
+ read_external_media_file,
create_project,
save_project,
runtime_status,
@@ -1353,6 +1629,16 @@ mod tests {
serde_json::from_str(include_str!("../../fixtures/project-v1-created.json")).unwrap()
}
+ /// A project whose video and audio live OUTSIDE the folder, alongside a
+ /// copied image — every shape the two location fields can take, in one
+ /// file both validators read.
+ fn external_fixture() -> ProjectConfig {
+ serde_json::from_str(include_str!(
+ "../../fixtures/project-v1-external-media.json"
+ ))
+ .unwrap()
+ }
+
/// The keys the frontend schema spells `.optional()` with NO `.nullable()`
/// (src/lib/project.ts lines 42-44, 56, 109). zod's `.optional()` rejects
/// `null`, so an explicit null under any of these names makes the whole
@@ -1476,6 +1762,13 @@ mod tests {
"rust-serialized-complete.json",
&serialize(&validate_and_normalize_config(fixture()).unwrap()),
);
+ // The external-location shapes: an absolute Windows path, an absolute
+ // POSIX one, a UNC share, and a copied image beside them. Rust writes
+ // exactly these bytes; the frontend suite parses them with real zod.
+ write_fixture(
+ "rust-serialized-external-media.json",
+ &serialize(&validate_and_normalize_config(external_fixture()).unwrap()),
+ );
// An ACTUALLY IMPORTED reference: produced by the same function the
// create-project command calls, not a hand-written fixture record.
@@ -1841,10 +2134,12 @@ mod tests {
#[test]
fn stored_paths_are_normalized_and_escaping_paths_are_rejected() {
let mut normalized = fixture();
- normalized.assets[0].relative_path = ".\\media\\imported//macro.mp4".into();
+ normalized.assets[0].relative_path = Some(".\\media\\imported//macro.mp4".into());
assert_eq!(
- validate_and_normalize_config(normalized).unwrap().assets[0].relative_path,
- "media/imported/macro.mp4"
+ validate_and_normalize_config(normalized).unwrap().assets[0]
+ .relative_path
+ .as_deref(),
+ Some("media/imported/macro.mp4")
);
for path in [
@@ -1856,7 +2151,7 @@ mod tests {
"references/../outside.png",
] {
let mut escaping = fixture();
- escaping.assets[0].relative_path = path.into();
+ escaping.assets[0].relative_path = Some(path.into());
assert!(
validate_and_normalize_config(escaping).is_err(),
"accepted escaping path {path}"
@@ -1959,6 +2254,291 @@ mod tests {
.is_file());
}
+ #[test]
+ fn the_windows_verbatim_prefix_never_reaches_the_user() {
+ // `\\?\D:\tmp\news\News broadcast` is what canonicalize hands back and
+ // what the library rendered under every project. The prefix is an
+ // OS-level escape hatch; the user's path is the rest of it.
+ assert_eq!(
+ display_path(Path::new(r"\\?\D:\tmp\news\News broadcast")),
+ r"D:\tmp\news\News broadcast"
+ );
+ // A verbatim UNC path names a share. Stripping only `\\?\` would leave
+ // `UNC\studio-nas\shared`, which points at nothing.
+ assert_eq!(
+ display_path(Path::new(r"\\?\UNC\studio-nas\shared\Footage")),
+ r"\\studio-nas\shared\Footage"
+ );
+ // Everything else is already what it should be, prefix-shaped or not.
+ for path in [
+ r"D:\tmp\news",
+ "/home/nn/projects/news",
+ r"\\studio-nas\shared",
+ "relative/is/left/alone",
+ r"D:\?\odd\but\real",
+ ] {
+ assert_eq!(display_path(Path::new(path)), path);
+ }
+ // And the stripped form is what every command re-canonicalises, so a
+ // real project folder still opens by the name the user was shown.
+ let root = tempfile::tempdir().unwrap();
+ let created = create_project_in(root.path(), &fixture()).unwrap();
+ assert!(
+ !created.folder_path.starts_with(r"\\?\"),
+ "a verbatim path reached the frontend: {}",
+ created.folder_path
+ );
+ assert!(read_project(Path::new(&created.folder_path)).is_ok());
+ }
+
+ #[test]
+ fn video_and_audio_are_recorded_where_they_are_and_images_are_copied() {
+ let root = tempfile::tempdir().unwrap();
+ let project = root.path().join("project");
+ fs::create_dir(&project).unwrap();
+ let outside = root.path().join("Rushes");
+ fs::create_dir(&outside).unwrap();
+
+ for (name, bytes) in [
+ ("news broadcast.mp4", &b"video"[..]),
+ ("room tone.wav", &b"audio"[..]),
+ ("title card.png", &b"\x89PNG\r\n\x1a\n"[..]),
+ ] {
+ fs::write(outside.join(name), bytes).unwrap();
+ }
+
+ // A rush is not duplicated to make a folder "portable": the project
+ // records where it already is.
+ for name in ["news broadcast.mp4", "room tone.wav"] {
+ let imported = import_media_file(&outside.join(name), &project).unwrap();
+ assert_eq!(imported.relative_path, None, "{name} was copied");
+ let source = imported.source_path.expect("external media needs a path");
+ assert!(
+ !source.starts_with(r"\\?\"),
+ "a verbatim path was stored: {source}"
+ );
+ assert_eq!(
+ normalize_external_path(&source).unwrap(),
+ source,
+ "{name} stored a path the schema would reject"
+ );
+ assert!(Path::new(&source).is_file());
+ }
+ // A picture is small, and a project's own artwork should travel with it.
+ let image = import_media_file(&outside.join("title card.png"), &project).unwrap();
+ assert_eq!(image.relative_path.as_deref(), Some("media/title card.png"));
+ assert_eq!(image.source_path, None);
+ assert!(project.join("media/title card.png").is_file());
+
+ // Nothing but the image ever landed inside the project folder.
+ let copied: Vec<_> = fs::read_dir(project.join("media"))
+ .unwrap()
+ .filter_map(Result::ok)
+ .map(|entry| entry.file_name().to_string_lossy().into_owned())
+ .collect();
+ assert_eq!(copied, ["title card.png"]);
+ }
+
+ #[test]
+ fn a_video_reference_is_pointed_at_while_an_image_reference_is_copied() {
+ let root = tempfile::tempdir().unwrap();
+ let project = root.path().join("project");
+ fs::create_dir(&project).unwrap();
+ let video = root.path().join("reference cut.mov");
+ fs::write(&video, b"video").unwrap();
+ let image = root.path().join("harbor facade.png");
+ fs::write(&image, b"\x89PNG\r\n\x1a\n").unwrap();
+
+ let referenced = import_reference_file(&video, &project).unwrap();
+ assert_eq!(referenced.kind, "video");
+ assert_eq!(referenced.relative_path, None);
+ assert!(referenced.source_path.is_some());
+ assert!(
+ !project.join("references").join("reference cut.mov").exists(),
+ "a video reference was copied into the project"
+ );
+
+ let copied = import_reference_file(&image, &project).unwrap();
+ assert_eq!(copied.kind, "image");
+ assert_eq!(
+ copied.relative_path.as_deref(),
+ Some("references/harbor facade.png")
+ );
+ assert_eq!(copied.source_path, None);
+ assert!(project.join("references/harbor facade.png").is_file());
+ }
+
+ #[test]
+ fn external_media_is_readable_only_because_the_project_names_it() {
+ let root = tempfile::tempdir().unwrap();
+ let outside = root.path().join("Rushes");
+ fs::create_dir(&outside).unwrap();
+ let clip = outside.join("rush-01.mp4");
+ fs::write(&clip, b"rush bytes").unwrap();
+ let secret = outside.join("id_rsa");
+ fs::write(&secret, b"private key").unwrap();
+ let unlisted = outside.join("rush-02.mp4");
+ fs::write(&unlisted, b"another rush").unwrap();
+
+ let mut config = created_fixture();
+ config.assets.push(ProjectAsset {
+ id: "asset-external".into(),
+ kind: "video".into(),
+ name: "Rush 01".into(),
+ relative_path: None,
+ source_path: Some(external_source_path(&clip).unwrap()),
+ mime_type: "video/mp4".into(),
+ duration_ms: None,
+ width: None,
+ height: None,
+ created_at: config.created_at.clone(),
+ });
+ let created = create_project_in(root.path(), &config).unwrap();
+ let folder = created.folder_path.as_str();
+ let recorded = created.config.assets[0].source_path.clone().unwrap();
+
+ // The file the user picked, which the project now names.
+ assert_eq!(
+ external_media_bytes(folder, &recorded).unwrap(),
+ b"rush bytes"
+ );
+
+ // A media file next to it that the project does NOT name.
+ let error = external_media_bytes(folder, &unlisted.to_string_lossy()).unwrap_err();
+ assert!(error.contains("not one of the files this project points at"));
+
+ // And the shape this command must never take: reading anything the
+ // caller asks for. A path the project does not carry is refused
+ // whatever it points at.
+ assert!(external_media_bytes(folder, &secret.to_string_lossy()).is_err());
+ assert!(external_media_bytes(folder, "/etc/passwd").is_err());
+ }
+
+ #[test]
+ fn a_project_file_only_yields_media_a_hand_edit_cannot_widen() {
+ // Belt and braces for the direction the allow-list alone cannot cover:
+ // a HAND-EDITED project file naming something that is not media. The
+ // path is recorded, so the allow-list passes — the extension check is
+ // what refuses it.
+ let root = tempfile::tempdir().unwrap();
+ let secret = root.path().join("id_rsa");
+ fs::write(&secret, b"private key").unwrap();
+
+ let mut config = created_fixture();
+ config.assets.push(ProjectAsset {
+ id: "asset-crafted".into(),
+ kind: "video".into(),
+ name: "Not a clip".into(),
+ relative_path: None,
+ source_path: Some(external_source_path(&secret).unwrap()),
+ mime_type: "video/mp4".into(),
+ duration_ms: None,
+ width: None,
+ height: None,
+ created_at: config.created_at.clone(),
+ });
+ let created = create_project_in(root.path(), &config).unwrap();
+ let recorded = created.config.assets[0].source_path.clone().unwrap();
+ let error = external_media_bytes(&created.folder_path, &recorded).unwrap_err();
+ assert!(
+ error.contains("not a media file"),
+ "unexpected error: {error}"
+ );
+ }
+
+ #[test]
+ fn every_stored_location_is_one_place_and_only_one() {
+ let external = external_fixture();
+ let normalized = validate_and_normalize_config(external.clone()).unwrap();
+ assert_eq!(
+ normalized.assets[0].source_path.as_deref(),
+ Some(r"D:\tmp\news\News broadcast\rush-01.mp4"),
+ "an external path is stored verbatim, not rewritten as a relative one"
+ );
+ assert!(normalized.assets[0].relative_path.is_none());
+
+ // Both at once is not a location, and neither is neither.
+ let mut both = external_fixture();
+ both.assets[0].relative_path = Some("media/rush-01.mp4".into());
+ assert!(validate_and_normalize_config(both)
+ .unwrap_err()
+ .contains("cannot have both"));
+ let mut neither = external_fixture();
+ neither.assets[0].source_path = None;
+ assert!(validate_and_normalize_config(neither)
+ .unwrap_err()
+ .contains("must have either"));
+
+ // A "source path" that is not absolute resolves against nothing.
+ for path in [
+ "Footage\\clip.mp4",
+ "media/clip.mp4",
+ "..\\..\\clip.mp4",
+ "D:\\..\\clip.mp4",
+ "",
+ ] {
+ let mut relative = external_fixture();
+ relative.assets[0].source_path = Some(path.into());
+ assert!(
+ validate_and_normalize_config(relative).is_err(),
+ "accepted '{path}' as an absolute source path"
+ );
+ }
+ // Every absolute form is accepted on every platform: a project file
+ // written on Windows is still read on Linux and back.
+ for path in [
+ "D:\\Footage\\clip.mp4",
+ "D:/Footage/clip.mp4",
+ "/home/nn/clip.mp4",
+ "\\\\nas\\share\\clip.mp4",
+ ] {
+ let mut absolute = external_fixture();
+ absolute.assets[0].source_path = Some(path.into());
+ assert!(
+ validate_and_normalize_config(absolute).is_ok(),
+ "rejected the absolute path '{path}'"
+ );
+ }
+
+ // References follow the same rule, and a file-backed one still needs
+ // its file.
+ let mut both_on_reference = external_fixture();
+ both_on_reference.references[1].relative_path = Some("references/cut.mov".into());
+ assert!(validate_and_normalize_config(both_on_reference).is_err());
+ let mut nowhere = external_fixture();
+ nowhere.references[1].source_path = None;
+ assert!(validate_and_normalize_config(nowhere).is_err());
+ }
+
+ #[test]
+ fn the_settings_file_is_polstudio_json_and_the_older_names_still_open() {
+ assert_eq!(PROJECT_FILE_NAME, "polstudio.json");
+ let root = tempfile::tempdir().unwrap();
+ let created = create_project_in(root.path(), &fixture()).unwrap();
+ let folder = PathBuf::from(&created.folder_path);
+ assert!(folder.join("polstudio.json").is_file());
+
+ // Every older name still opens, one folder per name, because a project
+ // written by an earlier build must not become unopenable.
+ for legacy in LEGACY_PROJECT_FILE_NAMES {
+ let old = root.path().join(format!("old-{legacy}"));
+ fs::create_dir(&old).unwrap();
+ fs::copy(folder.join(PROJECT_FILE_NAME), old.join(legacy)).unwrap();
+ assert_eq!(
+ read_project(&old).unwrap().config,
+ created.config,
+ "a project stored as {legacy} failed to open"
+ );
+ // Saving migrates the name and leaves the old file where it is, so
+ // the build that wrote it can still read the project.
+ write_project(&old, &created.config).unwrap();
+ assert!(old.join(PROJECT_FILE_NAME).is_file());
+ assert!(old.join(legacy).is_file());
+ // The new name wins once both exist.
+ assert_eq!(project_file_in(&old), old.join(PROJECT_FILE_NAME));
+ }
+ }
+
#[test]
fn sanitizes_folder_names() {
assert_eq!(safe_folder_name(" Launch: Film? "), "Launch- Film-");
@@ -1980,6 +2560,7 @@ mod tests {
description: String::new(),
content: None,
relative_path: None,
+ source_path: None,
intended_use: Vec::new(),
created_at: "2026-01-01T00:07:00.000Z".into(),
});
diff --git a/src/components/workspace/GeneratorView.tsx b/src/components/workspace/GeneratorView.tsx
index b53eb0b..34ead36 100644
--- a/src/components/workspace/GeneratorView.tsx
+++ b/src/components/workspace/GeneratorView.tsx
@@ -2,7 +2,7 @@ import { listen } from "@tauri-apps/api/event";
import { AlertCircle, Ban, Check, ChevronRight, Clock3, Film, Info, LoaderCircle, Play, Plus, RefreshCw, Sparkles, Square, WandSparkles, X } from "lucide-react";
import { useEffect, useMemo, useRef, useState } from "react";
import { isTauri } from "../../lib/persistence";
-import { compileMiniMaxH3Prompt, createDraftGenerationJob, STORY_TRACK_ID, isReferenceDescribed, isReferenceUsable, isVisualReference, projectFilePath, usableImageReferences, type GenerationJob, type ProjectAsset, type ProjectConfig, type ProjectReference, type TimelineClip, type TimelineTrack } from "../../lib/project";
+import { compileMiniMaxH3Prompt, createDraftGenerationJob, STORY_TRACK_ID, isReferenceDescribed, isReferenceUsable, isVisualReference, projectItemPath, usableImageReferences, type GenerationJob, type ProjectAsset, type ProjectConfig, type ProjectReference, type TimelineClip, type TimelineTrack } from "../../lib/project";
import { cancelVidfabGeneration, enqueueVidfabGeneration, resolveVidfabPlan, type VidfabGenerationRequest, type VidfabStatus } from "../../lib/runtime";
interface GeneratorViewProps {
@@ -79,7 +79,7 @@ export function GeneratorView({ config, folderPath, runtime = null, onChange, on
seed: 482091,
aspectRatio: config.settings.aspectRatio,
referencePaths: usableImageReferences(bound)
- .map((reference) => projectFilePath(folderPath, reference.relativePath ?? ""))
+ .map((reference) => projectItemPath(folderPath, reference) ?? "")
.filter((path) => path.length > 0),
};
};
diff --git a/src/components/workspace/MediaThumbnail.tsx b/src/components/workspace/MediaThumbnail.tsx
index 6ab9f79..b9d18be 100644
--- a/src/components/workspace/MediaThumbnail.tsx
+++ b/src/components/workspace/MediaThumbnail.tsx
@@ -1,6 +1,6 @@
import { Image as ImageIcon, Music2, TriangleAlert, Video } from "lucide-react";
import { useEffect, useState } from "react";
-import { readProjectFileUrl } from "../../lib/persistence";
+import { readMediaFileUrl } from "../../lib/persistence";
import type { ProjectAsset } from "../../lib/project";
/* A real picture of the media, not a striped placeholder.
@@ -80,7 +80,7 @@ async function imagePoster(url: string): Promise<string> {
}
export function MediaThumbnail({ folderPath, asset }: { folderPath: string; asset: ProjectAsset }) {
- const cacheKey = `${folderPath}::${asset.relativePath}`;
+ const cacheKey = `${folderPath}::${asset.sourcePath ?? asset.relativePath}`;
const [poster, setPoster] = useState<string | null>(() => POSTER_CACHE.get(cacheKey) ?? null);
const [failed, setFailed] = useState(false);
@@ -92,7 +92,7 @@ export function MediaThumbnail({ folderPath, asset }: { folderPath: string; asse
void (async () => {
let url: string | null = null;
try {
- url = await readProjectFileUrl(folderPath, asset.relativePath, asset.mimeType);
+ url = await readMediaFileUrl(folderPath, asset, asset.mimeType);
// Browser preview: there is no project folder, so there is nothing to
// show and nothing has gone wrong. The kind icon stands in.
if (!url) return;
@@ -106,7 +106,7 @@ export function MediaThumbnail({ folderPath, asset }: { folderPath: string; asse
}
})();
return () => { live = false; };
- }, [cacheKey, folderPath, asset.relativePath, asset.mimeType, asset.kind]);
+ }, [cacheKey, folderPath, asset, asset.mimeType, asset.kind]);
if (poster) {
return <span className="media-thumb media-thumb--poster">
diff --git a/src/components/workspace/ReferenceImage.tsx b/src/components/workspace/ReferenceImage.tsx
index 4063527..2bf4a31 100644
--- a/src/components/workspace/ReferenceImage.tsx
+++ b/src/components/workspace/ReferenceImage.tsx
@@ -1,18 +1,19 @@
import { Image as ImageIcon, TriangleAlert } from "lucide-react";
import { useEffect, useState } from "react";
-import { readProjectFileUrl } from "../../lib/persistence";
+import { readMediaFileUrl } from "../../lib/persistence";
-/* Reference images live in the project folder, which the webview cannot reach
- * directly — so the bytes come back through a Tauri command and become a blob
- * URL here. The URL is revoked on unmount and on every path change; without
+/* An image reference is copied into the project folder; a video or sound
+ * reference is left where the user keeps it and only its absolute path is
+ * recorded. Either way the webview cannot reach the file directly — so the
+ * bytes come back through a Tauri command and become a blob URL here. The URL is revoked on unmount and on every path change; without
* that, browsing a library of references pins each one in memory for the life
* of the window.
*
* The extension is the only thing available to type the blob: nothing has
* decoded the file. Getting it wrong costs a broken <img>, which is exactly
* what `failed` renders. */
-const mimeFor = (relativePath: string) => {
- const extension = relativePath.split(".").pop()?.toLowerCase();
+const mimeFor = (path: string) => {
+ const extension = path.split(".").pop()?.toLowerCase();
switch (extension) {
case "png": return "image/png";
case "webp": return "image/webp";
@@ -21,9 +22,12 @@ const mimeFor = (relativePath: string) => {
}
};
-export function ReferenceImage({ folderPath, relativePath, alt, className = "" }: {
+export function ReferenceImage({ folderPath, relativePath, sourcePath = null, alt, className = "" }: {
folderPath: string;
- relativePath: string;
+ /** Set for a file copied into the project. */
+ relativePath?: string | null;
+ /** Set instead for a file the project only points at. */
+ sourcePath?: string | null;
alt: string;
className?: string;
}) {
@@ -35,7 +39,7 @@ export function ReferenceImage({ folderPath, relativePath, alt, className = "" }
let live = true;
setFailed(false);
setUrl(null);
- void readProjectFileUrl(folderPath, relativePath, mimeFor(relativePath))
+ void readMediaFileUrl(folderPath, { relativePath, sourcePath }, mimeFor(sourcePath ?? relativePath ?? ""))
.then((value) => {
// Unmounted (or moved to another reference) while the read was in
// flight: revoke immediately, because nothing else ever will.
@@ -52,7 +56,7 @@ export function ReferenceImage({ folderPath, relativePath, alt, className = "" }
live = false;
if (current) URL.revokeObjectURL(current);
};
- }, [folderPath, relativePath]);
+ }, [folderPath, relativePath, sourcePath]);
if (url) {
return <img className={className} src={url} alt={alt} loading="lazy" onError={() => setFailed(true)} />;
diff --git a/src/components/workspace/ReferencesView.tsx b/src/components/workspace/ReferencesView.tsx
index eae4bde..435d7d8 100644
--- a/src/components/workspace/ReferencesView.tsx
+++ b/src/components/workspace/ReferencesView.tsx
@@ -83,12 +83,12 @@ export function ReferencesView({ config, folderPath, onChange }: { config: Proje
<div className="reference-library__toolbar"><span>{config.references.length === 1 ? "1 reference" : `${config.references.length} references`}</span></div>
<div className="reference-grid">
{config.references.map((ref) => <button key={ref.id} className={selectedId === ref.id ? "selected" : ""} onClick={() => setSelectedId(ref.id)}>
- {ref.kind === "image" && ref.relativePath
- ? <span className="reference-art reference-art--photo"><ReferenceImage folderPath={folderPath} relativePath={ref.relativePath} alt={ref.name} /></span>
+ {ref.kind === "image" && (ref.relativePath || ref.sourcePath)
+ ? <span className="reference-art reference-art--photo"><ReferenceImage folderPath={folderPath} relativePath={ref.relativePath} sourcePath={ref.sourcePath} alt={ref.name} /></span>
: ref.kind === "image"
? <span className="reference-art"><Image size={26} /><em>Image file</em></span>
: <span className="reference-copy-art"><FileText size={26} /><em>Text definition</em></span>}
- <span className="reference-card__body"><span><b>{ref.name}</b><small>{ref.kind === "text" ? "Text definition" : ref.relativePath}</small></span>{isReferenceDescribed(ref)
+ <span className="reference-card__body"><span><b>{ref.name}</b><small>{ref.kind === "text" ? "Text definition" : ref.relativePath ?? ref.sourcePath}</small></span>{isReferenceDescribed(ref)
? <p>{ref.description}</p>
: <p className="reference-card__incomplete">{ref.kind === "image"
? "Not described yet — the picture is sent, but nothing tells the engine what to keep."
@@ -107,11 +107,11 @@ export function ReferencesView({ config, folderPath, onChange }: { config: Proje
<aside className="reference-inspector">
<div className="panel-chrome"><h2>Reference details</h2>{selected && <button onClick={remove} aria-label="Delete reference" title="Delete this reference"><Trash2 size={16} /></button>}</div>
{selected ? <>
- <div className={`reference-detail-art reference-detail-art--${selected.kind}${selected.kind === "image" && selected.relativePath ? " reference-detail-art--photo" : ""}`}>
- {selected.kind === "image" && selected.relativePath
- ? <ReferenceImage folderPath={folderPath} relativePath={selected.relativePath} alt={selected.name} />
+ <div className={`reference-detail-art reference-detail-art--${selected.kind}${selected.kind === "image" && (selected.relativePath || selected.sourcePath) ? " reference-detail-art--photo" : ""}`}>
+ {selected.kind === "image" && (selected.relativePath || selected.sourcePath)
+ ? <ReferenceImage folderPath={folderPath} relativePath={selected.relativePath} sourcePath={selected.sourcePath} alt={selected.name} />
: <span>{selected.kind === "image" ? <Image size={30} /> : <Users size={30} />}</span>}
- <em>{selected.kind === "image" ? selected.relativePath : "Reusable text definition"}</em>
+ <em>{selected.kind === "image" ? selected.relativePath ?? selected.sourcePath : "Reusable text definition"}</em>
</div>
<div className="reference-fields">
<label><span>Name</span><input value={selected.name} onChange={(event) => update(selected.id, { name: event.target.value || "Untitled reference" })} /></label>
@@ -126,7 +126,7 @@ export function ReferencesView({ config, folderPath, onChange }: { config: Proje
<h3>Used by <span>{jobs.length}</span></h3>
{jobs.length ? jobs.map((job) => <div key={job.id}><span className={`job-link-dot job-link-dot--${job.status}`} /><div><b>{job.title}</b><small>{job.status} · {job.stage}</small></div><Link2 size={16} /></div>) : <p>No shots use this reference yet. Each new shot picks up the first two it can use from this list, so it will be used once it reaches the top two of those.</p>}
</section>
- <section className="portable-path"><BookOpen size={16} /><div><b>Where this lives</b><code>{selected.relativePath ?? "Stored in pols.json"}</code></div></section>
+ <section className="portable-path"><BookOpen size={16} /><div><b>Where this lives</b><code>{selected.relativePath ?? selected.sourcePath ?? "Stored in polstudio.json"}</code></div></section>
</> : <div className="reference-empty"><BookOpen size={26} /><b>Select a reference</b><p>Pick one from the library, or add a new one, to edit its definition and see which generations use it.</p></div>}
</aside>
</div>
diff --git a/src/components/workspace/TimelineView.tsx b/src/components/workspace/TimelineView.tsx
index 2dcfae3..d52d245 100644
--- a/src/components/workspace/TimelineView.tsx
+++ b/src/components/workspace/TimelineView.tsx
@@ -168,7 +168,10 @@ export function TimelineView({ config, folderPath, onChange, onOpenGenerator }:
id: `asset-${crypto.randomUUID()}`,
kind: file.kind,
name: file.name,
+ // Images are copied in; video and sound are left where they are and
+ // carry an absolute path instead. Exactly one of the two is set.
relativePath: file.relativePath,
+ sourcePath: file.sourcePath,
mimeType: file.mimeType,
// Genuinely unknown until something decodes the file. Left null rather
// than filled with a plausible number.
@@ -301,7 +304,7 @@ export function TimelineView({ config, folderPath, onChange, onOpenGenerator }:
className="media-import"
onClick={() => void importMedia()}
disabled={importing || !isTauri()}
- title={isTauri() ? "Copy video, sound, or image files into this project" : "Importing files is available in the desktop app"}
+ title={isTauri() ? "Add video, sound, or image files — video and sound stay where they are, images are copied in" : "Importing files is available in the desktop app"}
>
<Upload size={20} /><b>{importing ? "Importing…" : "Import media"}</b>
</button>
diff --git a/src/lib/persistence.ts b/src/lib/persistence.ts
index 923eaf0..74749df 100644
--- a/src/lib/persistence.ts
+++ b/src/lib/persistence.ts
@@ -7,6 +7,7 @@ import {
type PendingReferenceImage,
type ProjectConfig,
type ProjectRecord,
+ type StoredLocation,
} from "./project";
const RECENTS_KEY = "polstudio.recent-projects.v1";
@@ -146,19 +147,25 @@ export async function chooseInitialReferenceImages(): Promise<PendingReferenceIm
return invoke<PendingReferenceImage[]>("choose_initial_reference_images");
}
-/** A file the user picked, already copied into the project's `media/` folder.
+/** 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: PolStudio 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;
+ relativePath: string | null;
+ sourcePath: string | null;
mimeType: string;
}
-/** Opens the picker and copies what was chosen into the project. Returns an
- * empty list when the user cancels — and in the browser, where there is no
- * project folder to copy into. */
+/** 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 });
@@ -174,6 +181,21 @@ export async function readProjectFileUrl(folderPath: string, relativePath: strin
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/lib.rs. Same revoke rule as `readProjectFileUrl`. */
+export async function readMediaFileUrl(folderPath: string, item: StoredLocation, mimeType: string): Promise<string | null> {
+ if (!isTauri()) return null;
+ const bytes = item.sourcePath
+ ? await invoke<ArrayBuffer>("read_external_media_file", { folderPath, sourcePath: item.sourcePath })
+ : item.relativePath
+ ? await invoke<ArrayBuffer>("read_project_file", { folderPath, relativePath: item.relativePath })
+ : null;
+ return bytes ? URL.createObjectURL(new Blob([bytes], { type: mimeType })) : null;
+}
+
export async function createProject(input: CreateProjectInput): Promise<ProjectRecord | null> {
const config = createProjectConfig(input);
if (isTauri()) {
diff --git a/src/lib/project.test.ts b/src/lib/project.test.ts
index f7af928..9dd299c 100644
--- a/src/lib/project.test.ts
+++ b/src/lib/project.test.ts
@@ -1,7 +1,9 @@
import { describe, expect, it } from "vitest";
import completeFixture from "../../fixtures/project-v1-complete.json";
import createdFixture from "../../fixtures/project-v1-created.json";
+import externalFixture from "../../fixtures/project-v1-external-media.json";
import wireCreated from "../../fixtures/rust-serialized-created.json";
+import wireExternal from "../../fixtures/rust-serialized-external-media.json";
import wireComplete from "../../fixtures/rust-serialized-complete.json";
import initialReferenceWire from "../../fixtures/rust-serialized-initial-reference.json";
@@ -9,19 +11,28 @@ import {
compileMiniMaxH3Prompt,
createProjectConfig,
deriveH3Style,
+ isExternalItem,
isReferenceUsable,
normalizeProjectPath,
parseProjectConfig,
projectFilePath,
+ projectItemPath,
projectNameFromPrompt,
projectReferenceSchema,
seedProjectWorkspace,
STORY_TRACK_ID,
usableImageReferences,
+ LEGACY_PROJECT_FILE_NAMES,
+ PROJECT_FILE_NAME,
type ProjectReference,
} from "./project";
/** Regenerated by `cargo test` from the Rust validator's real output. */
-const wireFixtures = { created: wireCreated, complete: wireComplete, initialReference: initialReferenceWire };
+const wireFixtures = {
+ created: wireCreated,
+ complete: wireComplete,
+ initialReference: initialReferenceWire,
+ externalMedia: wireExternal,
+};
/** Body of one compiled section, for both prompt shapes: T2VA writes
* `name: value` on one line, full-reference mode writes `name:\nvalue`, and in
@@ -364,6 +375,74 @@ describe("project schema", () => {
expect(projectFilePath("/home/nn/lighthouse/", "references/a.jpg")).toBe("/home/nn/lighthouse/references/a.jpg");
});
+ it("keeps video and audio where they are, and resolves both kinds of location", () => {
+ // The whole point of the external location: a 40 GB rush is referenced, not
+ // duplicated into the project folder.
+ const config = parseProjectConfig(externalFixture);
+ const video = config.assets.find((asset) => asset.id === "asset-external-video")!;
+ const image = config.assets.find((asset) => asset.id === "asset-copied-image")!;
+ expect(video.relativePath ?? null).toBeNull();
+ expect(video.sourcePath).toBe("D:\\tmp\\news\\News broadcast\\rush-01.mp4");
+ expect(isExternalItem(video)).toBe(true);
+ expect(isExternalItem(image)).toBe(false);
+
+ // An external path is already absolute and must come back untouched; a
+ // copied one resolves against the project folder. Resolving an external
+ // clip against the folder would name a file that was never there.
+ expect(projectItemPath("D:\\Projects\\News", video)).toBe("D:\\tmp\\news\\News broadcast\\rush-01.mp4");
+ expect(projectItemPath("D:\\Projects\\News", image)).toBe("D:\\Projects\\News\\media\\title-card.png");
+ expect(projectItemPath("D:\\Projects\\News", { relativePath: null, sourcePath: null })).toBeNull();
+
+ // A reference behaves the same way: the image is copied in, the video is not.
+ const externalReference = config.references.find((reference) => reference.kind === "video")!;
+ expect(externalReference.sourcePath).toBe("\\\\studio-nas\\shared\\reference cut.mov");
+ expect(config.references.find((reference) => reference.kind === "image")!.relativePath)
+ .toBe("references/harbor facade.png");
+ // Only images are sent to the engine, so a video reference is not one of
+ // the <Picture N> assets however it is stored.
+ expect(usableImageReferences(config.references).map((reference) => reference.id)).toEqual(["ref-copied-image"]);
+ });
+
+ it("accepts a project written before external media existed", () => {
+ // Every asset in this fixture carries a relativePath and no sourcePath —
+ // exactly what every project written by an earlier build looks like.
+ const config = parseProjectConfig(completeFixture);
+ expect(config.assets.every((asset) => asset.relativePath && !asset.sourcePath)).toBe(true);
+ });
+
+ it("refuses a location that is ambiguous, missing, or not absolute", () => {
+ const withAsset = (over: Record<string, unknown>) => {
+ const config = structuredClone(completeFixture) as any;
+ config.assets[0] = { ...config.assets[0], ...over };
+ return () => parseProjectConfig(config);
+ };
+ // Both at once: nothing downstream could say which file is meant.
+ expect(withAsset({ sourcePath: "D:\\Footage\\clip.mp4" })).toThrow();
+ // Neither: an asset with no file is not an asset.
+ expect(withAsset({ relativePath: null, sourcePath: null })).toThrow();
+ // A relative "external" path resolves against nothing at all.
+ for (const path of ["Footage\\clip.mp4", "media/clip.mp4", "..\\..\\clip.mp4", "D:\\..\\clip.mp4", ""]) {
+ expect(withAsset({ relativePath: null, sourcePath: path }), path).toThrow();
+ }
+ // The three absolute forms are accepted on every platform: a project file
+ // written on Windows is still read on Linux and back.
+ for (const path of ["D:\\Footage\\clip.mp4", "D:/Footage/clip.mp4", "/home/nn/clip.mp4", "\\\\nas\\share\\clip.mp4"]) {
+ expect(withAsset({ relativePath: null, sourcePath: path })(), path).toBeTruthy();
+ }
+ // And a reference cannot claim both either.
+ const bothOnReference = structuredClone(completeFixture) as any;
+ bothOnReference.references[1] = { ...bothOnReference.references[1], sourcePath: "D:\\Footage\\ref.png" };
+ expect(() => parseProjectConfig(bothOnReference)).toThrow();
+ });
+
+ it("names the settings file polstudio.json and remembers what it used to be", () => {
+ expect(PROJECT_FILE_NAME).toBe("polstudio.json");
+ // Both older names still open a project (project_file_in, Rust side); only
+ // the current one is ever written.
+ expect(LEGACY_PROJECT_FILE_NAMES).toEqual(["pols.json", "polstudio.project.json"]);
+ expect(LEGACY_PROJECT_FILE_NAMES).not.toContain(PROJECT_FILE_NAME);
+ });
+
it("parses the complete cross-layer fixture without losing data", () => {
expect(parseProjectConfig(completeFixture)).toEqual(completeFixture);
});
@@ -425,7 +504,10 @@ describe("project schema", () => {
expect(project.timeline.tracks.flatMap((track) => track.clips).every((clip) => trackIds.has(clip.trackId))).toBe(true);
expect(project.generationJobs.some((job) => job.status === "generating")).toBe(true);
expect(project.references.some((reference) => reference.kind === "image")).toBe(true);
- expect(project.assets.every((asset) => !asset.relativePath.match(/^([a-z]:|[/\\])/i))).toBe(true);
+ // The seeded workspace is entirely project-owned: every asset is a file
+ // inside the folder, none of them points outside it.
+ expect(project.assets.every((asset) => !asset.sourcePath)).toBe(true);
+ expect(project.assets.every((asset) => !asset.relativePath?.match(/^([a-z]:|[/\\])/i))).toBe(true);
expect(project.generationJobs.filter((job) => job.outputRelativePath).every((job) => !job.outputRelativePath!.match(/^([a-z]:|[/\\])/i))).toBe(true);
});
});
diff --git a/src/lib/project.ts b/src/lib/project.ts
index 078dee0..648691c 100644
--- a/src/lib/project.ts
+++ b/src/lib/project.ts
@@ -1,6 +1,10 @@
import { z } from "zod";
-export const PROJECT_FILE_NAME = "pols.json";
+export const PROJECT_FILE_NAME = "polstudio.json";
+/** What the settings file used to be called, newest first. Both are still
+ * opened (`project_file_in` in src-tauri/src/lib.rs); only the current name is
+ * ever written. */
+export const LEGACY_PROJECT_FILE_NAMES = ["pols.json", "polstudio.project.json"] as const;
export const CURRENT_SCHEMA_VERSION = 1 as const;
const idSchema = z.string().min(1);
@@ -30,6 +34,56 @@ export const projectRelativePathSchema = z.string().transform((value, context) =
}
});
+/** The other kind of stored location: a file the project points at but does not
+ * contain. Video and audio are never copied into a project — a folder of
+ * rushes is tens of gigabytes — so the project records where the user already
+ * keeps them.
+ *
+ * It must be ABSOLUTE, because nothing resolves it: no project root, no
+ * working directory. `..` is refused so the recorded string is the same string
+ * every comparison sees. Separators are left exactly as the OS wrote them, and
+ * all three absolute forms are accepted on every platform, because a project
+ * file written on Windows is still parsed by tests (and by a reader) on Linux.
+ *
+ * Mirrors `normalize_external_path` in src-tauri/src/lib.rs. The two must
+ * agree in BOTH directions — Rust writes this file before zod ever sees it. */
+export function normalizeExternalPath(value: string): string {
+ if (!value || value.includes("\0")) throw new Error("External media paths cannot be empty or contain null bytes.");
+ const absolute = /^[a-zA-Z]:[\\/]/.test(value) || value.startsWith("\\\\") || value.startsWith("/");
+ if (!absolute) throw new Error("External media must be recorded as an absolute path.");
+ if (value.split(/[\\/]/).includes("..")) throw new Error("External media paths cannot contain '..'.");
+ return value;
+}
+
+export const externalPathSchema = z.string().transform((value, context) => {
+ try {
+ return normalizeExternalPath(value);
+ } catch (error) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: error instanceof Error ? error.message : "Invalid external path.",
+ });
+ return z.NEVER;
+ }
+});
+
+/** Anything with a file behind it: inside the project, or outside it. */
+export interface StoredLocation {
+ relativePath?: string | null;
+ sourcePath?: string | null;
+}
+
+/** Every location is one of the two and never both, so nothing downstream has
+ * to decide which wins. Shared by assets and references. */
+function checkOneLocation(value: StoredLocation, context: z.RefinementCtx, label: string): void {
+ if (value.relativePath && value.sourcePath) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom, path: ["sourcePath"],
+ message: `${label} cannot have both a project-relative path and an external source path.`,
+ });
+ }
+}
+
export const aspectRatioSchema = z.enum(["16:9", "9:16", "1:1", "4:5"]);
export const resolutionSchema = z.enum(["720p", "1080p", "4k"]);
@@ -37,7 +91,14 @@ export const projectAssetSchema = z.object({
id: idSchema,
kind: z.enum(["video", "audio", "image", "caption", "generated"]),
name: z.string().min(1),
- relativePath: projectRelativePathSchema,
+ // Exactly one of the two. `relativePath` is a file COPIED into the project
+ // folder — images, and everything generated here; `sourcePath` is a file left
+ // where the user keeps it — video and audio, which are far too big to
+ // duplicate. Both are `.nullish()`: Rust omits the absent one, and a project
+ // written before this field existed has only `relativePath`, so both must
+ // survive an absent key.
+ relativePath: projectRelativePathSchema.nullish(),
+ sourcePath: externalPathSchema.nullish(),
mimeType: z.string().min(1),
// `.nullish()`, not `.optional()`. Rust serialises a `None` as an explicit
// JSON `null` unless the field carries skip_serializing_if, and a bare
@@ -48,6 +109,14 @@ export const projectAssetSchema = z.object({
width: z.number().int().positive().nullish(),
height: z.number().int().positive().nullish(),
createdAt: isoDateSchema,
+}).superRefine((asset, context) => {
+ checkOneLocation(asset, context, `Asset '${asset.id}'`);
+ if (!asset.relativePath && !asset.sourcePath) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom, path: ["relativePath"],
+ message: `Asset '${asset.id}' must have either a project-relative path or an external source path.`,
+ });
+ }
});
export const timelineClipSchema = z.object({
@@ -82,18 +151,29 @@ export const generationBriefSchema = z.object({
export const projectReferenceSchema = z.object({
id: idSchema,
- kind: z.enum(["text", "image"]),
+ // `video` and `audio` are file-backed like an image, but are never copied
+ // into the project: only their absolute path is recorded. Nothing in the UI
+ // creates one yet — both reference pickers are image-only — so this is what
+ // the file format can hold, not a promise about a button.
+ kind: z.enum(["text", "image", "video", "audio"]),
name: z.string().min(1),
// May be empty: a reference can exist before the user has described it, and
// pre-filling it with instruction text would feed that text to the model.
description: z.string(),
content: z.string().min(1).nullable().optional(),
relativePath: projectRelativePathSchema.nullable().optional(),
+ // An image reference is copied into `references/`; a video or audio one is
+ // pointed at where it lives. See the note on projectAssetSchema.sourcePath.
+ sourcePath: externalPathSchema.nullish(),
intendedUse: z.array(z.enum(["character", "product", "location", "style", "audio"])).default([]),
createdAt: isoDateSchema,
}).superRefine((reference, context) => {
- if (reference.kind === "image" && !reference.relativePath) {
- context.addIssue({ code: z.ZodIssueCode.custom, path: ["relativePath"], message: "Image references require a relative path." });
+ checkOneLocation(reference, context, `Reference '${reference.id}'`);
+ if (reference.kind !== "text" && !reference.relativePath && !reference.sourcePath) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom, path: ["relativePath"],
+ message: `A ${reference.kind} reference needs the file it refers to.`,
+ });
}
});
@@ -197,6 +277,23 @@ export function projectFilePath(folderPath: string, relativePath: string): strin
return `${root}${separator}${relativePath.split(/[\\/]/).join(separator)}`;
}
+/** Where an asset or reference actually is on disk, whichever kind of location
+ * it carries. The ONE place that decides: a file copied into the project
+ * resolves against the project folder, a file left outside it is already
+ * absolute and is returned untouched. Null only for a record with no file at
+ * all — a text reference.
+ *
+ * Every consumer must go through this. Reading `relativePath` alone silently
+ * resolves an external clip against the project folder, which produces a path
+ * to a file that was never there. */
+export function projectItemPath(folderPath: string, item: StoredLocation): string | null {
+ if (item.sourcePath) return item.sourcePath;
+ return item.relativePath ? projectFilePath(folderPath, item.relativePath) : null;
+}
+
+/** Whether this record's file lives outside the project folder. */
+export const isExternalItem = (item: StoredLocation): boolean => Boolean(item.sourcePath);
+
/** The words the USER wrote about a reference, or "" — never a library label
* and never anything this app authored. Both import paths used to seed
* `description` with filing boilerplate ("Visual reference copied into this
@@ -221,7 +318,7 @@ export function isReferenceDescribed(reference: ProjectReference): boolean {
* as <Picture N> with nothing written about it. */
export function isReferenceUsable(reference: ProjectReference): boolean {
return reference.kind === "image"
- ? Boolean(reference.relativePath)
+ ? Boolean(reference.relativePath ?? reference.sourcePath)
: isReferenceDescribed(reference);
}