Skip to content

Catalog assets

Generated from openspec/specs/catalog-assets/spec.md — edit that file, not this page.

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.

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-null gltfUrl, 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 assets row 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-refine kind on the asset row, and leaves the asset in generating so 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 ready with 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 dimsMm and 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 assets row 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
  • 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
  • WHEN an asset’s gltfUrl is 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-upload or meshy-image completes successfully
  • THEN it produces an assets row 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