Add textures for sprites

Images are uploaded to a content-addressed blob endpoint and stored as
data/textures/<sha256>.<ext>; the project only keeps the file name. The
sprite points at a texture asset through an ordinary property of the new
kind `asset`, so instance overrides, "Apply to container", "Reset to
asset", undo and `Set property` work without any extra code. The new kind
also replaces the ad-hoc asset picker the graph nodes faked as an enum.

Import goes through + -> Texture, drag & drop onto the canvas or Ctrl+V.
Images wider than 2048px are downscaled client-side and re-encoded to
WebP if needed, because nginx caps uploads at 1MB; an image that already
fits is uploaded byte for byte so pixel art is never resampled.

The sprite colour default changes from red to white, since colour tints
the texture multiplicatively and a tint of white shows an image as it is.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/core/model/Asset.ts

@@ -65,9 +65,41 @@ export interface ContainerAsset extends AssetBase {
   objects: SceneObject[];
 }
 
+/**
+ * An uploaded image. `file` names it in `data/textures/` and is content-addressed
+ * (`{sha256}.{ext}`), so the same picture uploaded twice is one file and a stored file can be
+ * cached forever – its name cannot ever come to mean different bytes.
+ *
+ * Like a scene's objects and a behavior's graph, this is intrinsic data rather than a
+ * property: nothing about it is editable or overridable per instance. What *is* a property
+ * is the reference to it – sprites carry `texture` (see PropertySchema), which is how
+ * instance overrides, "Apply to container" and `Set property` work on it for free.
+ *
+ * `width`/`height` are the pixel size as uploaded, kept so a sprite can be sized to its
+ * picture without waiting for the image to load. An empty `file` means the upload failed or
+ * has not happened yet; such a texture draws as nothing.
+ */
+export interface TextureAsset extends AssetBase {
+  type: 'texture';
+  file: string;
+  width: number;
+  height: number;
+}
+
 export type Asset =
-  SpriteAsset | CameraAsset | TextAsset | SceneAsset | BehaviorAsset | ColliderAsset | ContainerAsset;
+  | SpriteAsset
+  | CameraAsset
+  | TextAsset
+  | SceneAsset
+  | BehaviorAsset
+  | ColliderAsset
+  | ContainerAsset
+  | TextureAsset;
 
 export function isSceneAsset(asset: Asset): asset is SceneAsset {
   return asset.type === 'scene';
 }
+
+export function isTextureAsset(asset: Asset): asset is TextureAsset {
+  return asset.type === 'texture';
+}

src/core/model/AssetTypes.ts

@@ -1,4 +1,4 @@
-/** All asset types. Scenes are assets too, but cannot be placed in scenes. */
+/** All asset types. Scenes and textures are assets too, but cannot be placed in scenes. */
 export const ASSET_TYPES = [
   'scene',
   'camera',
@@ -7,6 +7,7 @@ export const ASSET_TYPES = [
   'behavior',
   'collider',
   'container',
+  'texture',
 ] as const;
 
 export type AssetType = (typeof ASSET_TYPES)[number];
@@ -20,13 +21,18 @@ export const ASSET_TYPE_LABELS: Record<AssetType, string> = {
   behavior: 'Behavior',
   collider: 'Collider',
   container: 'Container',
+  texture: 'Texture',
 };
 
-/** Types that can be placed into a scene (everything except scenes themselves). */
-export type PlaceableAssetType = Exclude<AssetType, 'scene'>;
+/**
+ * Types that can be placed into a scene. A texture is not one of them: it is picture data,
+ * not something with a position – a sprite wears it (see the `texture` property). Dropping a
+ * texture into the scene therefore creates a sprite, it does not place the texture itself.
+ */
+export type PlaceableAssetType = Exclude<AssetType, 'scene' | 'texture'>;
 
 export function isPlaceableType(type: AssetType): type is PlaceableAssetType {
-  return type !== 'scene';
+  return type !== 'scene' && type !== 'texture';
 }
 
 export function isAssetType(value: unknown): value is AssetType {

src/core/model/Project.ts

@@ -1,3 +1,4 @@
+import { schemaForAsset } from '../properties/PropertySchema';
 import { type Asset, type ContainerAsset, isSceneAsset, type SceneAsset } from './Asset';
 import type { SceneObject } from './SceneObject';
 
@@ -63,3 +64,40 @@ export function objectsWhere(
 export function findUsages(project: Project, assetId: string): SceneObjectRef[] {
   return objectsWhere(project, (o) => o.assetId === assetId);
 }
+
+/** One place where an `asset`-kind property points at an asset. */
+export type PropertyUsage =
+  | { on: 'asset'; asset: Asset; key: string }
+  | { on: 'object'; holder: ObjectHolder; object: SceneObject; key: string };
+
+/**
+ * Every property that references `assetId`, on assets and on the overrides of placed objects.
+ *
+ * This is the other half of "where is this asset used": `findUsages` finds assets that were
+ * *placed*, which is meaningless for a texture – a texture is never placed, it is worn by
+ * sprites through their `texture` property. Deleting one therefore has to count both, or it
+ * reports "0 uses" for a picture that ten sprites are showing.
+ *
+ * A reference is deliberately left dangling rather than cleared when its asset goes: a
+ * dangling one resolves to "no picture" everywhere it is read, and it comes back by itself
+ * when the delete is undone.
+ */
+export function findPropertyUsages(project: Project, assetId: string): PropertyUsage[] {
+  if (!assetId) return [];
+  const result: PropertyUsage[] = [];
+  const assetKeys = new Map<string, string[]>();
+  for (const asset of project.assets) {
+    const keys = schemaForAsset(asset)
+      .filter((def) => def.kind === 'asset')
+      .map((def) => def.key);
+    assetKeys.set(asset.id, keys);
+    for (const key of keys) if (asset.props[key] === assetId) result.push({ on: 'asset', asset, key });
+  }
+  for (const holder of objectHolders(project)) {
+    for (const object of holder.objects) {
+      for (const key of assetKeys.get(object.assetId) ?? [])
+        if (object.overrides[key] === assetId) result.push({ on: 'object', holder, object, key });
+    }
+  }
+  return result;
+}

src/core/model/texture.ts

@@ -0,0 +1,34 @@
+import type { PropertyBag } from './Properties';
+import { findAsset, type Project } from './Project';
+
+/**
+ * A stored image file name: `{sha256}.{png|jpg|webp|gif}`. Mirrors `TextureStore::isValidName`
+ * on the server – the name is derived from the bytes there, so anything else in a document
+ * was hand-written and must not be turned into a request.
+ */
+const FILE_PATTERN = /^[a-f0-9]{64}\.(png|jpg|webp|gif)$/;
+
+export function isTextureFile(name: string): boolean {
+  return FILE_PATTERN.test(name);
+}
+
+/** A picture ready to be drawn: which file, and whether to smooth it when scaled. */
+export interface TextureRef {
+  file: string;
+  /** False for pixel art, where interpolation is the difference between crisp and mush. */
+  smooth: boolean;
+}
+
+/**
+ * The picture a bag of properties points at, or null when it points at nothing usable –
+ * no reference, a dangling one (the texture was deleted), or one whose upload never
+ * finished. Callers draw their plain colour in that case, which is what a sprite looked
+ * like before textures existed.
+ */
+export function resolveTexture(project: Project, props: PropertyBag): TextureRef | null {
+  const id = String(props.texture ?? '');
+  if (!id) return null;
+  const asset = findAsset(project, id);
+  if (asset?.type !== 'texture' || !isTextureFile(asset.file)) return null;
+  return { file: asset.file, smooth: String(asset.props.filter ?? 'linear') !== 'nearest' };
+}