@forgeax/engine-graphics-extras 0.1.2

package/src/video-loader.ts

@@ -0,0 +1,80 @@
+// @forgeax/engine-graphics-extras - video loader (feat-20260623-world-space-video-asset M2 / w4).
+//
+// Descriptor-only loader for the 'video' asset kind. VideoAsset is a pure
+// `{ url }` descriptor (no pixel decode, no import/cook pipeline — OOS-1);
+// the runtime resolves it into an HTMLVideoElement via the host-provided
+// `VideoElementProvider` World Resource (plan-strategy D-1).
+//
+// The loader returns the payload as VideoAsset synchronously — no fetch or
+// decode. Audio differs because its renderer-injected catalog-entry loader
+// fetches and decodes a Web Audio payload before cataloguing it.
+//
+// Registered in wireDefaultLoaders alongside the other 10 default kinds
+// (plan-strategy D-7: engine-own kind goes in the default set so AI users
+// don't have to manually register it).
+
+import {
+  type AssetDecoderContribution,
+  type AssetKind,
+  err,
+  type Loader,
+  ok,
+  type VideoAsset,
+} from '@forgeax/engine-types';
+
+const VIDEO_URL_RESOLUTION_BASE = 'https://forgeax.invalid/';
+const VIDEO_URL_WHITESPACE = /\s/u;
+
+function hasVideoUrlControlCharacter(value: string): boolean {
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    if (code <= 0x1f || code === 0x7f) return true;
+  }
+  return false;
+}
+
+function isBrowserResolvableVideoUrl(value: unknown): value is string {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.trim().length === 0 ||
+    value !== value.trim() ||
+    hasVideoUrlControlCharacter(value) ||
+    VIDEO_URL_WHITESPACE.test(value) ||
+    value.startsWith('//')
+  ) {
+    return false;
+  }
+  try {
+    const resolved = new URL(value, VIDEO_URL_RESOLUTION_BASE);
+    return resolved.protocol === 'http:' || resolved.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+export const videoLoader: Loader<VideoAsset> = {
+  kind: 'video',
+  load(payload: Record<string, unknown>): VideoAsset | undefined {
+    if (!isBrowserResolvableVideoUrl(payload.url)) return undefined;
+    return { kind: 'video', url: payload.url };
+  },
+};
+
+export const videoContribution: AssetDecoderContribution<VideoAsset, 'video'> = {
+  kind: { kind: 'video' } as AssetKind<VideoAsset, 'video'>,
+  consumer: 'VideoElementProvider',
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload;
+      return payload.kind === 'video' && isBrowserResolvableVideoUrl(payload.url)
+        ? ok(payload)
+        : err({
+            code: 'asset-package-invalid',
+            expected: 'a browser-resolvable video URL descriptor',
+            hint: 'publish an http(s) video URL and let the host create the video element',
+            detail: { guid: envelope.guid, reason: 'video owner validation failed' },
+          });
+    },
+  },
+};

package/src/video-player-system.ts

@@ -0,0 +1,61 @@
+// @forgeax/engine-graphics-extras — video high-perf upload capability probe
+// (feat-20260623-world-space-video-asset M4 / w17).
+//
+// The single per-frame video upload path lives in the record stage
+// (`render-system-record.ts` `videoTextureView`): it reads the host-registered
+// VideoElementProvider (World Resource, D-1), uploads the current frame via
+// `DynamicTextureStore.uploadFrame` (copyExternalImageToTexture), and fires the
+// structured `VideoUploadUnsupportedError` on the engine error channel when a
+// VideoPlayer entity can reach NEITHER the general path (no host element) NOR
+// the high-perf path (AC-10 double-miss, charter P3). There is exactly ONE video
+// upload/failure path — this module only contributes the capability probe the
+// record stage consults to decide whether the reserved high-perf branch is
+// available.
+//
+// Decision anchors:
+//   - requirements AC-09 (two paths left in place, capability probe explicit).
+//   - plan-strategy D-2 (grep-able capability branch, not a TODO).
+
+/**
+ * Minimal device shape the high-perf capability probe inspects: the backend
+ * kind plus the (currently-absent) `importExternalTexture` method. Declared
+ * structurally so the probe stays decoupled from the full RhiDevice surface and
+ * unit tests drive it with a small object.
+ */
+export interface VideoCapabilityDevice {
+  readonly caps: { readonly backendKind: 'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null' };
+  /**
+   * The WebGPU zero-copy video import entry point. forgeax exposes NO such RHI
+   * method today (research Finding 4 confirmed `importExternalTexture` grep=0),
+   * so this is always `undefined` — the probe's presence check is the explicit,
+   * grep-able boundary between the general path and the reserved high-perf path
+   * (D-2 / AC-09; OOS-5 keeps the upload body unimplemented).
+   */
+  readonly importExternalTexture?: unknown;
+}
+
+/**
+ * AC-09 / D-2 capability probe: decide whether the high-perf zero-copy
+ * GPUExternalTexture upload path is available for video this frame. This is the
+ * EXPLICIT reserved hook the AC-09 "two paths left in place" acceptance is
+ * checked against by code review — it is a real, grep-able code branch, not a
+ * TODO comment.
+ *
+ * The high-perf path requires BOTH a WebGPU backend (GPUExternalTexture is a
+ * browser-WebGPU feature) AND the RHI exposing an `importExternalTexture` entry
+ * point. The latter does not exist in forgeax today (OOS-5: importing the
+ * external texture + a `texture_external` MaterialParamType + WGSL external
+ * sampling is out of scope), so this probe ALWAYS returns false and the general
+ * `copyExternalImageToTexture` path (record stage) is the sole route end-to-end.
+ * The day a future feat lands `importExternalTexture`, this probe flips on for
+ * WebGPU backends without touching the call sites.
+ */
+export function probeVideoHighPerfUpload(device: VideoCapabilityDevice | undefined): boolean {
+  if (device === undefined) return false;
+  // GPUExternalTexture is browser-WebGPU only (wgpu-native / wgpu-webgl2 lack it).
+  if (device.caps.backendKind !== 'webgpu') return false;
+  // Reserved high-perf hook: available only when the RHI exposes the import
+  // entry point. It is absent today (OOS-5), so this is the false-returning
+  // boundary the AC-09 two-path code review verifies.
+  return typeof device.importExternalTexture === 'function';
+}

package/src/video-player.ts

@@ -0,0 +1,51 @@
+// @forgeax/engine-graphics-extras — VideoPlayer ECS component
+// (feat-20260623-world-space-video-asset M3 / w7).
+//
+// Single-component play-state surface for world-space video textures. An
+// entity carries one VideoPlayer referencing a VideoAsset via the `clip`
+// handle; the per-entity playing / loop / currentTime live in independent
+// archetype column slots so multiple entities share one VideoAsset GUID with
+// independent play state (AC-05, research Finding 6).
+//
+// Schema vocab is the CLOSED ECS set (component.ts:315-333): clip uses
+// `shared<VideoAsset>` (a branded u32 handle, NOT a bare GUID string), the
+// three play-state fields use `bool` / `f32`. No opaque / object field type is
+// introduced — the host HTMLVideoElement reference travels through the
+// VideoElementProvider World Resource (plan-strategy D-1 / w9), never inside an
+// ECS field (research Finding 5: schema vocab closed).
+//
+// Decision anchors:
+//   - requirements AC-04 (VideoPlayer registers via defineComponent; reference
+//     field is a handle type, not a bare GUID; play-state fields playing/loop/
+//     currentTime).
+//   - plan-strategy D-4 (clip: Handle<'VideoAsset','shared'>, brand string
+//     'VideoAsset' mirrors AudioSource.clip: Handle<'AudioClipAsset','shared'>
+//     so AI users carry over the audio naming intuition — charter P4).
+//   - charter P1 (progressive disclosure: 4-field minimal surface).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * VideoPlayer — attaches video play state to an entity.
+ *
+ * Fields:
+ *   - `clip: shared<VideoAsset>` — handle to the VideoAsset describing the
+ *     source URL (mirrors `AudioSource.clip`). Resolved into an
+ *     HTMLVideoElement at frame time via the host `VideoElementProvider`
+ *     (the engine never decodes video bytes — D-1).
+ *   - `playing: bool` — whether the clip advances this frame (default false).
+ *   - `loop: bool` — whether the clip restarts at end (default false).
+ *   - `currentTime: f32` — playback head in seconds (default 0).
+ *
+ * Multiple entities may reference the same `clip` GUID with distinct
+ * play state — each entity's playing / loop / currentTime occupy independent
+ * archetype column slots (AC-05).
+ */
+export const VideoPlayer = defineComponent('VideoPlayer', {
+  // The host HTMLVideoElement owns the live asset/presentation binding; the
+  // portable play controls remain in the simulation projection.
+  clip: { type: 'shared<VideoAsset>' },
+  playing: { type: 'bool', default: false },
+  loop: { type: 'bool', default: false },
+  currentTime: { type: 'f32', default: 0, transient: true },
+});