Asset system: organize assets into folders

[kfarr]

Summary

Let users organize items in the asset system (generated images, AI renders, uploads, meshes) into folders.

Motivation

A paying customer running a multi-week visualization project accumulates a large number of generated images and prompt iterations — the account behind this request has 209 assets, most of them AI renders of the same few buildings at different prompt settings. In a flat list, finding "the good version of the building" means scrolling through a wall of near-identical thumbnails. The asset library becomes less useful the more you use the product, which is backwards.

Scope

This is the asset system, distinct from two neighboring asks. Ordered by priority:

1. Scene graph grouping — grouping entities within a scene. Already tracked: milestone "2. Grouping (Basic)" (Ability to group child entities in a "group" parent entity #1183, Ability to move multiple selected entities under folder #1187, Custom sidebar for group entity #1196, Cascading selection of entities -- click parent group before selecting child entities #1231).
2. Asset system folders — this issue.
3. Scene system folders — organizing saved scenes in the project list. Separate issue.

Proposed behavior

• Create, rename, and delete folders in the asset library.
• Move assets into a folder, including multi-select.
• Assets remain reachable regardless of folder when inserting into a scene.
• Nesting: one level is probably enough to start; deep trees can wait for evidence anyone wants them.

Open questions

• Do folders need to be shared/visible across a team on Pro Team plans, or are they per-user?
• Should AI renders auto-group by source scene, given the asset metadata already records sceneId and sceneTitle? That may deliver most of the value with no manual filing at all.

Idea: auto-group by source scene (implementer's call)

Asset metadata already records sceneId and sceneTitle, so assets could be grouped automatically with no manual filing at all. Offered as an option for whoever picks this up, not a settled requirement — manual folders may still be the right primary mechanism.

Measured against one heavy account to size the idea:

• 209 assets across 9 scenes
• 176 (84%) carry a sceneId
• Per-scene counts: 73, 47, 21, 14, 8, 5, 5, 3

Auto-grouping is a strong default: it turns a 209-item flat wall into 9 buckets for free. But it is not a complete substitute — the largest bucket is still 73 assets and would want sub-organization of its own, and unfiled assets need somewhere to live. A plausible shape is auto-grouping as the default view with manual folders layered on top, but that is for the implementer to decide.

Related: derivative assets carry no provenance

The 84% coverage above is dragged down by something broader than a missing field, and worth understanding before designing around sceneId.

No generator records which asset its input image came from. Every path takes input_image as raw pixel data — a data URL — with no reference to the source asset:

Path	Input	Scene provenance sent
video.js	params.input_image = this.imageData	none
model3d.js	input_image: this.imageData	scene_id: null
splat.js	payload.input_image = this.sourceImageData	none

The result in the sampled account: 17 of 17 ai-render videos lack a sceneId, 3 of 3 splat outputs lack one, and 7 of 7 uploaded meshes lack one. Ai-render images, generated directly from a scene, have one 102 times out of 105. The split is total, which is what identifies it as a code path rather than a data quirk.

The remaining 3 unfiled images are source: 'generator' — made on the standalone generator page rather than from a scene, so genuinely scene-less. Correct behavior, not a bug.

Why this is not just "add scene_id to the video params." A video today is generated from an image, which was itself generated from or captured of a scene. Attributing the video to a scene means propagating provenance through a derivative work, and the same is true of image-to-3D-model and splat generation. The question is not a missing parameter but whether the asset system should model lineage at all.

Two shapes, and this is a design decision rather than a settled one:

1. Copy sceneId forward at generation time. Cheap, and enough for grouping. Loses the intermediate step — you know the video relates to the scene but not which render it came from.
2. Record parentAssetId and derive sceneId transitively. Generalizes to every derivative path, and supports "show me everything derived from this render." Requires generators to accept an asset reference rather than only pixels, which is the real work.

Option 2 is the better model and the larger change. Option 1 unblocks grouping now. Worth deciding deliberately, because option 1 taken casually is the kind of thing that makes option 2 harder later.

• Decide between copy-forward and parentAssetId lineage.
• Thread the chosen provenance through video, 3D-model, and splat generation — not video alone.
• Decide whether to backfill existing derivative assets (likely not worth it).