Catalog assets
Generated from
openspec/specs/catalog-assets/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”The catalog is Tinkerspace’s library of placeable 3D content (furniture, fixtures, lighting, decor) and texture-backed materials that designers use in floorplan scenes. It guarantees that assets arriving through any acquisition path (AI generation, direct upload, craft composition, or admin batch import) converge on the same canonical, optimized, org-scoped, real-world-scaled representation before a client can load them.
Requirements
Section titled “Requirements”Requirement: Multi-path asset acquisition
Section titled “Requirement: Multi-path asset acquisition”The system SHALL accept new catalog assets through Meshy text-to-3D generation, Meshy image-to-3D generation, direct GLB upload, Meshy retexture (variant) generation, craft compositions, and admin batch import, and SHALL converge every path on the same assets row shape before the asset is usable.
Scenario: Direct GLB upload creates a usable asset
Section titled “Scenario: Direct GLB upload creates a usable asset”- WHEN a designer completes the three-step upload flow (create metadata row, PUT raw GLB bytes, PUT a rendered thumbnail)
- THEN the asset row has
status="ready", a non-nullgltfUrl, and a thumbnail, and it appears in that designer’s catalog list
Scenario: Meshy generation failure inserts no row
Section titled “Scenario: Meshy generation failure inserts no row”- WHEN Meshy rejects a text-to-3D or image-to-3D generation request
- THEN the API responds with an error and does not insert an
assetsrow for that request
Requirement: Text-to-3D completes its texture pass before going ready
Section titled “Requirement: Text-to-3D completes its texture pass before going ready”The system SHALL treat a successful Meshy text-to-3D preview as an intermediate state, not a finished asset, and SHALL chain the refine pass that bakes PBR textures onto the preview geometry before marking the asset ready — on every path that drives generation to completion, both the client-facing refresh route and the offline seeding scripts.
Scenario: Succeeding preview chains into refine
Section titled “Scenario: Succeeding preview chains into refine”- WHEN a text-to-3D preview task reports
SUCCEEDED - THEN the system starts a refine task, records the new task id and a
text-to-3d-refinekind on the asset row, and leaves the asset ingeneratingso the caller keeps polling
Scenario: Refine kick-off failure degrades to preview geometry
Section titled “Scenario: Refine kick-off failure degrades to preview geometry”- WHEN the refine task cannot be started (for example the Meshy account is out of credits)
- THEN the asset is marked
readywith the untextured preview geometry rather than failed, so the work already paid for is not lost and the asset can be re-textured later
Requirement: GLB optimization before canonical serving
Section titled “Requirement: GLB optimization before canonical serving”The system SHALL NOT serve raw provider-issued GLB bytes to clients as the canonical asset; every GLB SHALL pass through a gltf-transform optimization pass before it is treated as model.glb.
Scenario: Uploaded or copied GLB is queued for optimization
Section titled “Scenario: Uploaded or copied GLB is queued for optimization”- WHEN a GLB is written to an asset’s storage key (via direct upload or admin batch import)
- THEN the system enqueues an optimize job for that asset so a compressed derivative is produced without blocking the request that wrote the bytes
Requirement: Real-world scale is dims-driven, not GLB-derived
Section titled “Requirement: Real-world scale is dims-driven, not GLB-derived”The system SHALL treat the generated or uploaded GLB’s own vertex extent as untrusted and SHALL scale every placed asset to an explicit dims (width/depth/height, millimeters) bounding box stored on the asset row.
Scenario: New asset gets a category default and is editable
Section titled “Scenario: New asset gets a category default and is editable”- WHEN an asset-creation flow (generate, generate-from-image, or upload) does not receive explicit dims
- THEN the row is created with
ASSET_CATEGORY_DEFAULT_DIMS[category]as its dims, and the creation UI presents those dims as editable width/depth/height inputs before the asset is finalized
Scenario: Editing dims does not resize already-placed instances
Section titled “Scenario: Editing dims does not resize already-placed instances”- WHEN a designer edits an existing catalog asset’s dims via the catalog fix-up route
- THEN floorplan scene items that already placed that asset keep their own previously-copied
dimsMmand are unaffected, while future placements inherit the updated dims
Requirement: Four-level visibility scoping
Section titled “Requirement: Four-level visibility scoping”The system SHALL scope every catalog asset to one of four visibility levels — private (creator only), org (members of the asset’s organization), shared (creator plus explicit per-user grants), platform (everyone, including anonymous callers) — and SHALL enforce that scoping on both list queries and single-asset reads.
Scenario: Non-visible asset read returns not-found, not forbidden
Section titled “Scenario: Non-visible asset read returns not-found, not forbidden”- WHEN a caller requests a single asset they are not authorized to see under its visibility rules
- THEN the API responds 404, not 403, so the asset’s existence is not revealed to the caller
Scenario: Platform assets are visible to anonymous callers
Section titled “Scenario: Platform assets are visible to anonymous callers”- WHEN an unauthenticated request lists or fetches an asset with
visibility="platform" - THEN the asset is included in the response
Requirement: Creator-only deletion with best-effort storage cleanup
Section titled “Requirement: Creator-only deletion with best-effort storage cleanup”The system SHALL restrict asset deletion to the asset’s creator and SHALL remove the database row before attempting to clean up its storage objects, so a partial storage failure never leaves an orphaned database row.
Scenario: Delete removes the row then attempts R2 cleanup
Section titled “Scenario: Delete removes the row then attempts R2 cleanup”- WHEN a creator deletes their asset
- THEN the
assetsrow is deleted, and the system best-effort deletes the asset’s model, mobile-profile, original, and thumbnail objects from R2, tolerating individual object-delete failures
Scenario: Non-creator cannot delete
Section titled “Scenario: Non-creator cannot delete”- WHEN a user who is not the asset’s creator (including an org admin) requests deletion
- THEN the request is rejected and the row is not deleted
Requirement: Client-rendered, versioned thumbnails
Section titled “Requirement: Client-rendered, versioned thumbnails”The system SHALL generate catalog thumbnails client-side (as Workers cannot render WebGL) as JPEG images, SHALL cap accepted thumbnail uploads, and SHALL track a render-version per asset so future rendering-pipeline changes can trigger regeneration.
Scenario: Oversized or wrong-format thumbnail upload is rejected
Section titled “Scenario: Oversized or wrong-format thumbnail upload is rejected”- WHEN a thumbnail upload exceeds the server’s size cap or fails the accepted-image-format check
- THEN the upload is rejected and the asset’s existing thumbnail (if any) is left unchanged
Scenario: Stale thumbnail version triggers regeneration
Section titled “Scenario: Stale thumbnail version triggers regeneration”- WHEN an owner-visible asset’s stored thumbnail version is below the current thumbnail render version
- THEN the catalog’s background regeneration sweep re-renders and re-uploads that asset’s thumbnail
Requirement: GLB proxy is the sole client-facing model URL
Section titled “Requirement: GLB proxy is the sole client-facing model URL”The system SHALL serve every catalog GLB to clients through its own proxy endpoint, never a raw upstream provider URL, and SHALL treat a null gltfUrl as “not ready to serve.”
Scenario: Proxy transparently backfills R2 on first request
Section titled “Scenario: Proxy transparently backfills R2 on first request”- WHEN a client requests an asset’s model through the GLB proxy and the optimized bytes are not yet in R2
- THEN the proxy fetches the bytes from the upstream source, streams them to the client, and stores a copy in R2 for subsequent requests
Scenario: Null gltfUrl blocks serving
Section titled “Scenario: Null gltfUrl blocks serving”- WHEN an asset’s
gltfUrlis null - THEN the GLB proxy does not serve a model for that asset
Requirement: Admin batch import is explicitly org-scoped
Section titled “Requirement: Admin batch import is explicitly org-scoped”The system SHALL require a super-admin performing a batch import to explicitly select the target organization, since admins may import for organizations they are not members of, and SHALL process each batch item according to its declared kind (GLB upload or Meshy image-to-3D).
Scenario: Batch item becomes a normal catalog asset on success
Section titled “Scenario: Batch item becomes a normal catalog asset on success”- WHEN a batch import item of kind
glb-uploadormeshy-imagecompletes successfully - THEN it produces an
assetsrow scoped to the admin-selected target organization, indistinguishable from an asset created through any other acquisition path
Scenario: Failed batch item retries then dead-letters
Section titled “Scenario: Failed batch item retries then dead-letters”- WHEN processing a batch item fails
- THEN the system retries the item via the queue’s retry mechanism and marks it dead-lettered after repeated failures, without silently dropping it