@empty-sekai/sekai-custom-profile-sdk 0.3.0

package/src/gpu/semanticCommandGeometry.ts

@@ -0,0 +1,260 @@
+import type { SemanticDrawOperation, SemanticResourceKey } from "./semanticCommandPlanner.js";
+
+export type SemanticDrawBatchKind = "shape" | "image" | "mask" | "text" | "composite";
+export type SemanticBlendMode = "src_over" | "src_in" | "dst_in" | "multiply" | "screen" | "add";
+export type SemanticCompositeOperation = "marker" | "begin_isolation" | "end_isolation";
+
+export type SemanticDrawBatch = {
+  kind: SemanticDrawBatchKind;
+  commandIds: string[];
+  operations: SemanticDrawOperation[];
+  vertices: Float32Array;
+  layerSlots: Uint32Array;
+  commandSlots: Uint32Array;
+  resource: SemanticResourceKey | null;
+  maskResource: SemanticResourceKey | null;
+  blendMode: SemanticBlendMode;
+  compositeOperation: SemanticCompositeOperation | null;
+};
+
+export const SEMANTIC_FLOATS_PER_VERTEX = 28;
+export function semanticTextBatchKey(commandIds: readonly string[]): string {
+  return `semantic-text-batch\0${commandIds.join("\0")}`;
+}
+const UNIT_TRIANGLES = [
+  [0, 0], [1, 0], [1, 1],
+  [0, 0], [1, 1], [0, 1],
+] as const;
+
+/** Compile immutable geometry only. Render mask and dynamic translation remain
+ * in the dense layer-state textures, so toggles/ticks never rebuild vertices. */
+export function compileSemanticDrawBatches(operations: SemanticDrawOperation[]): SemanticDrawBatch[] {
+  const groups: Array<{ key: string; kind: SemanticDrawBatchKind; resource: SemanticResourceKey | null; maskResource: SemanticResourceKey | null; blendMode: SemanticBlendMode; compositeOperation: SemanticCompositeOperation | null; operations: SemanticDrawOperation[] }> = [];
+  for (const operation of operations) {
+    const descriptor = batchDescriptor(operation);
+    const previous = groups.at(-1);
+    if (previous?.key === descriptor.key) previous.operations.push(operation);
+    else groups.push({ ...descriptor, operations: [operation] });
+  }
+  return groups.map((group) => compileGroup(group.kind, group.resource, group.maskResource, group.blendMode, group.compositeOperation, group.operations));
+}
+
+function batchDescriptor(operation: SemanticDrawOperation): {
+  key: string;
+  kind: SemanticDrawBatchKind;
+  resource: SemanticResourceKey | null;
+  maskResource: SemanticResourceKey | null;
+  blendMode: SemanticBlendMode;
+  compositeOperation: SemanticCompositeOperation | null;
+} {
+  const payload = operation.command.payload;
+  const blendMode = commandBlendMode(operation.command.blend_mode);
+  if (payload.kind === "image") {
+    const resource = requireResource(payload.resource, operation.command.id);
+    const maskResource = optionalResource(payload.alpha_mask);
+    const maskKey = maskResource ? `\0${maskResource.namespace}\0${maskResource.key}` : "";
+    return { key: `image\0${blendMode}\0${resource.namespace}\0${resource.key}${maskKey}`, kind: "image", resource, maskResource, blendMode, compositeOperation: null };
+  }
+  if (payload.kind === "shape") {
+    const maskResource = assetMaskResource(payload.primitive);
+    if (maskResource) return { key: `mask\0${blendMode}\0${maskResource.namespace}\0${maskResource.key}`, kind: "mask", resource: maskResource, maskResource: null, blendMode, compositeOperation: null };
+    return { key: `shape\0${blendMode}`, kind: "shape", resource: null, maskResource: null, blendMode, compositeOperation: null };
+  }
+  if (payload.kind === "text") return { key: `text\0${blendMode}`, kind: "text", resource: null, maskResource: null, blendMode, compositeOperation: null };
+  if (payload.kind === "composite") {
+    const compositeOperation = requireCompositeOperation(payload.operation, operation.command.id);
+    return { key: `composite\0${operation.command.id}`, kind: "composite", resource: null, maskResource: null, blendMode, compositeOperation };
+  }
+  throw new Error(`unsupported semantic command payload ${(payload as { kind?: unknown }).kind}`);
+}
+
+function compileGroup(
+  kind: SemanticDrawBatchKind,
+  resource: SemanticResourceKey | null,
+  maskResource: SemanticResourceKey | null,
+  blendMode: SemanticBlendMode,
+  compositeOperation: SemanticCompositeOperation | null,
+  operations: SemanticDrawOperation[]
+): SemanticDrawBatch {
+  if (kind === "text" || kind === "composite") {
+    return { kind, resource, maskResource, blendMode, compositeOperation, operations: [...operations], commandIds: operations.map((op) => op.command.id), vertices: new Float32Array(), layerSlots: new Uint32Array(), commandSlots: new Uint32Array() };
+  }
+  const vertices = new Float32Array(operations.length * 6 * SEMANTIC_FLOATS_PER_VERTEX);
+  const layerSlots = new Uint32Array(operations.length * 6);
+  const commandSlots = new Uint32Array(operations.length * 6);
+  let vertexOffset = 0;
+  for (const operation of operations) {
+    const bounds = requireRect(operation.command.bounds, operation.command.id);
+    const commandMatrix = requireMatrix(operation.command.matrix, operation.command.id);
+    const clip = commandClip(operation.command.clip, operation.baseMatrix, operation.command.id);
+    const payload = operation.command.payload;
+    const uv = payload.kind === "image" ? optionalRect(payload.uv) : { x: 0, y: 0, width: 1, height: 1 };
+    const fill = payload.kind === "image" ? optionalColor(payload.tint, [1, 1, 1, 1]) : optionalColor(payload.fill, [1, 1, 1, 1]);
+    const stroke = payload.kind === "shape" ? optionalColor(payload.stroke, [0, 0, 0, 0]) : [0, 0, 0, 0];
+    const [primitive, radiusX, radiusY] = payload.kind === "shape"
+      ? shapeParams(payload.primitive, bounds)
+      : payload.kind === "image" ? imageClipParams(payload.clip, bounds) : [0, 0, 0];
+    const strokeWidth = payload.kind === "shape" && typeof payload.stroke_width === "number"
+      ? payload.stroke_width
+      : 0;
+    for (const [unitX, unitY] of UNIT_TRIANGLES) {
+      const vertexFill = payload.kind === "shape" ? gradientColor(payload.gradient, unitX, unitY, fill) : fill;
+      const localX = bounds.x + bounds.width * unitX;
+      const localY = bounds.y + bounds.height * unitY;
+      const commandPoint = transformPoint(commandMatrix, localX, localY);
+      const [x, y] = transformPoint(operation.baseMatrix, commandPoint[0], commandPoint[1]);
+      const base = vertexOffset * SEMANTIC_FLOATS_PER_VERTEX;
+      vertices.set([
+        x, y,
+        uv.x + uv.width * unitX, uv.y + uv.height * unitY,
+        unitX, unitY,
+        ...vertexFill,
+        ...stroke,
+        primitive, radiusX, radiusY, strokeWidth,
+        ...clip[0], ...clip[1], ...clip[2], ...clip[3],
+        bounds.width, bounds.height,
+      ], base);
+      layerSlots[vertexOffset] = operation.layerSlot;
+      commandSlots[vertexOffset] = operation.commandSlot;
+      vertexOffset += 1;
+    }
+  }
+  return {
+    kind,
+    resource,
+    maskResource,
+    blendMode,
+    compositeOperation,
+    operations: [...operations],
+    commandIds: operations.map((operation) => operation.command.id),
+    vertices,
+    layerSlots,
+    commandSlots,
+  };
+}
+
+function commandBlendMode(value: unknown): SemanticBlendMode {
+  if (value == null) return "src_over";
+  if (value === "src_over" || value === "src_in" || value === "dst_in" || value === "multiply" || value === "screen" || value === "add") return value;
+  throw new Error(`unsupported semantic blend mode ${String(value)}`);
+}
+
+function requireCompositeOperation(value: unknown, commandId: string): SemanticCompositeOperation {
+  if (value == null || value === "marker") return "marker";
+  if (value === "begin_isolation" || value === "end_isolation") return value;
+  throw new Error(`unsupported composite operation ${commandId}: ${String(value)}`);
+}
+
+function commandClip(
+  value: unknown,
+  baseMatrix: [number, number, number, number, number, number],
+  commandId: string
+): [[number, number], [number, number], [number, number], [number, number]] {
+  if (value == null) return [[-1e9, -1e9], [1e9, -1e9], [1e9, 1e9], [-1e9, 1e9]];
+  if (!Array.isArray(value) || value.length !== 4 || value.some((point) => !Array.isArray(point) || point.length !== 2 || point.some((entry) => typeof entry !== "number" || !Number.isFinite(entry)))) {
+    throw new Error(`invalid command clip ${commandId}`);
+  }
+  return value.map((point) => transformPoint(baseMatrix, point[0], point[1])) as [[number, number], [number, number], [number, number], [number, number]];
+}
+
+function gradientColor(value: unknown, x: number, y: number, fallback: number[]): number[] {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fallback;
+  const gradient = value as Record<string, unknown>;
+  const start = optionalPoint(gradient.start, [0, 0.5]);
+  const end = optionalPoint(gradient.end, [1, 0.5]);
+  const startColor = optionalColor(gradient.start_color, fallback);
+  const endColor = optionalColor(gradient.end_color, fallback);
+  const dx = end[0] - start[0];
+  const dy = end[1] - start[1];
+  const lengthSq = dx * dx + dy * dy;
+  const t = lengthSq > 1e-9 ? Math.max(0, Math.min(1, ((x - start[0]) * dx + (y - start[1]) * dy) / lengthSq)) : 0;
+  return startColor.map((component, index) => component + (endColor[index] - component) * t);
+}
+
+function optionalPoint(value: unknown, fallback: [number, number]): [number, number] {
+  return Array.isArray(value) && value.length === 2 && value.every((entry) => typeof entry === "number" && Number.isFinite(entry))
+    ? [value[0], value[1]]
+    : fallback;
+}
+
+function transformPoint(matrix: [number, number, number, number, number, number], x: number, y: number): [number, number] {
+  return [matrix[0] * x + matrix[2] * y + matrix[4], matrix[1] * x + matrix[3] * y + matrix[5]];
+}
+
+function requireMatrix(value: unknown, commandId: string): [number, number, number, number, number, number] {
+  if (!Array.isArray(value) || value.length !== 6 || value.some((entry) => typeof entry !== "number" || !Number.isFinite(entry))) {
+    throw new Error(`invalid command matrix ${commandId}`);
+  }
+  return value as [number, number, number, number, number, number];
+}
+
+function requireRect(value: unknown, commandId: string): { x: number; y: number; width: number; height: number } {
+  const rect = optionalRect(value);
+  if (![rect.x, rect.y, rect.width, rect.height].every(Number.isFinite) || rect.width < 0 || rect.height < 0) {
+    throw new Error(`invalid command bounds ${commandId}`);
+  }
+  return rect;
+}
+
+function optionalRect(value: unknown): { x: number; y: number; width: number; height: number } {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { x: 0, y: 0, width: 1, height: 1 };
+  const rect = value as Record<string, unknown>;
+  return {
+    x: Number(rect.x ?? 0),
+    y: Number(rect.y ?? 0),
+    width: Number(rect.width ?? 1),
+    height: Number(rect.height ?? 1),
+  };
+}
+
+function optionalColor(value: unknown, fallback: number[]): number[] {
+  return Array.isArray(value) && value.length === 4 && value.every((entry) => typeof entry === "number" && Number.isFinite(entry))
+    ? value
+    : fallback;
+}
+
+function shapeParams(value: unknown, _bounds: { width: number; height: number }): [number, number, number] {
+  if (value === "ellipse") return [2, 0, 0];
+  if (value === "rect") return [0, 0, 0];
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [0, 0, 0];
+  const rounded = (value as Record<string, unknown>).rounded_rect;
+  if (rounded && typeof rounded === "object" && !Array.isArray(rounded)) {
+    const radius = (rounded as Record<string, unknown>).radius;
+    if (Array.isArray(radius) && radius.length === 2) {
+      return [1, Number(radius[0]), Number(radius[1])];
+    }
+  }
+  return [0, 0, 0];
+}
+
+function imageClipParams(value: unknown, _bounds: { width: number; height: number }): [number, number, number] {
+  if (value === "ellipse") return [2, 0, 0];
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [0, 0, 0];
+  const rounded = (value as Record<string, unknown>).rounded_rect;
+  if (rounded && typeof rounded === "object" && !Array.isArray(rounded)) {
+    const radius = (rounded as Record<string, unknown>).radius;
+    if (Array.isArray(radius) && radius.length === 2) {
+      return [1, Number(radius[0]), Number(radius[1])];
+    }
+  }
+  return [0, 0, 0];
+}
+
+function assetMaskResource(value: unknown): SemanticResourceKey | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const mask = (value as Record<string, unknown>).asset_mask;
+  if (!mask || typeof mask !== "object" || Array.isArray(mask)) return null;
+  return requireResource((mask as Record<string, unknown>).resource, "asset-mask");
+}
+
+function requireResource(value: unknown, commandId: string): SemanticResourceKey {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`missing command resource ${commandId}`);
+  const resource = value as Record<string, unknown>;
+  if (typeof resource.namespace !== "string" || typeof resource.key !== "string") throw new Error(`invalid command resource ${commandId}`);
+  return { namespace: resource.namespace, key: resource.key };
+}
+
+function optionalResource(value: unknown): SemanticResourceKey | null {
+  if (value == null) return null;
+  return requireResource(value, "image-alpha-mask");
+}

package/src/gpu/semanticCommandPlanner.ts

@@ -0,0 +1,280 @@
+export type SemanticResourceKey = { namespace: string; key: string };
+
+export type SemanticCommand = {
+  id: string;
+  layer_id: string;
+  role: string;
+  payload: Record<string, unknown> & { kind: string };
+  [key: string]: unknown;
+};
+
+export type SemanticLayerPatch = {
+  layer_id: string;
+  render_mask: boolean | null;
+  transform: { dx: number; dy: number } | null;
+};
+
+export type SemanticCommandStatePatch = {
+  slot: number;
+  render_mask: boolean | null;
+  transform: { dx: number; dy: number } | null;
+};
+
+export type SemanticCommandPlanInput = {
+  layerTableRevision: number;
+  layerTable: Array<{
+    layer_id: string;
+    parent_id: string | null;
+    slot: number;
+    subtree_start: number;
+    subtree_end: number;
+  }>;
+  layerSources: Array<{
+    layer_id: string;
+    matrix: [number, number, number, number, number, number];
+  }>;
+  layerCommands: Array<{
+    layer_id: string;
+    render_mask: boolean;
+    transform: { dx: number; dy: number };
+    command_start: number;
+    command_count: number;
+  }>;
+  semanticCommands: SemanticCommand[];
+  commandStates?: Array<{
+    command_id: string;
+    slot: number;
+    render_mask: boolean;
+    transform: { dx: number; dy: number };
+  }>;
+};
+
+export type SemanticDrawOperation = {
+  command: SemanticCommand;
+  layerId: string;
+  layerSlot: number;
+  baseMatrix: [number, number, number, number, number, number];
+  visible: boolean;
+  transform: { dx: number; dy: number };
+  commandSlot: number;
+  commandVisible: boolean;
+  commandTransform: { dx: number; dy: number };
+};
+
+type LayerRuntimeState = {
+  slot: number;
+  baseMatrix: [number, number, number, number, number, number];
+  visible: boolean;
+  transform: { dx: number; dy: number };
+};
+
+/**
+ * Immutable authored-layer command ownership plus mutable render state.
+ * Visibility and dynamic deltas update only the dense state table; command
+ * order and resource identity remain stable for the plan lifetime.
+ */
+export class SemanticCommandPlan {
+  readonly layerTableRevision: number;
+  readonly commandRevision = 1;
+  readonly resourceRevision = 1;
+  private readonly commands: SemanticCommand[];
+  private readonly operationLayers: Array<{ layerId: string; slot: number }>;
+  private readonly stateByLayer = new Map<string, LayerRuntimeState>();
+  private readonly resources: SemanticResourceKey[];
+  private readonly commandVisible: boolean[];
+  private readonly commandTransforms: Array<{ dx: number; dy: number }>;
+
+  constructor(input: SemanticCommandPlanInput) {
+    this.layerTableRevision = input.layerTableRevision;
+    this.commands = [...input.semanticCommands];
+    const stateBySlot = input.commandStates ?? this.commands.map((command, slot) => ({
+      command_id: command.id,
+      slot,
+      render_mask: true,
+      transform: { dx: 0, dy: 0 },
+    }));
+    if (stateBySlot.length !== this.commands.length) throw new Error("command state table length mismatch");
+    this.commandVisible = new Array(this.commands.length);
+    this.commandTransforms = new Array(this.commands.length);
+    for (const state of stateBySlot) {
+      if (!Number.isInteger(state.slot) || state.slot < 0 || state.slot >= this.commands.length || this.commands[state.slot].id !== state.command_id) {
+        throw new Error(`command state identity mismatch at ${state.slot}`);
+      }
+      this.commandVisible[state.slot] = state.render_mask;
+      this.commandTransforms[state.slot] = { ...state.transform };
+    }
+    const tableByLayer = new Map<string, number>();
+    const matrixByLayer = new Map(input.layerSources.map((layer) => [layer.layer_id, layer.matrix] as const));
+    for (const entry of input.layerTable) {
+      if (tableByLayer.has(entry.layer_id)) throw new Error(`duplicate layer table id ${entry.layer_id}`);
+      if (!Number.isInteger(entry.slot) || entry.slot < 0) throw new Error(`invalid layer slot ${entry.slot}`);
+      tableByLayer.set(entry.layer_id, entry.slot);
+    }
+    const coverage = new Uint8Array(this.commands.length);
+    this.operationLayers = new Array(this.commands.length);
+    for (const layerCommand of input.layerCommands) {
+      const slot = tableByLayer.get(layerCommand.layer_id);
+      if (slot == null) throw new Error(`layer command references unknown layer ${layerCommand.layer_id}`);
+      if (this.stateByLayer.has(layerCommand.layer_id)) {
+        throw new Error(`duplicate layer command ${layerCommand.layer_id}`);
+      }
+      const baseMatrix = matrixByLayer.get(layerCommand.layer_id);
+      if (!baseMatrix) throw new Error(`missing authored layer matrix ${layerCommand.layer_id}`);
+      const start = layerCommand.command_start;
+      const end = start + layerCommand.command_count;
+      if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end > this.commands.length) {
+        throw new Error(`invalid command span for layer ${layerCommand.layer_id}`);
+      }
+      for (let index = start; index < end; index += 1) {
+        const command = this.commands[index];
+        if (coverage[index] !== 0 || command.layer_id !== layerCommand.layer_id) {
+          throw new Error(`command span ownership mismatch at ${index}`);
+        }
+        coverage[index] = 1;
+        this.operationLayers[index] = { layerId: layerCommand.layer_id, slot };
+      }
+      this.stateByLayer.set(layerCommand.layer_id, {
+        slot,
+        baseMatrix: [...baseMatrix] as LayerRuntimeState["baseMatrix"],
+        visible: layerCommand.render_mask,
+        transform: { ...layerCommand.transform },
+      });
+    }
+    const uncovered = coverage.findIndex((value) => value === 0);
+    if (uncovered >= 0) throw new Error(`semantic command ${uncovered} is outside every authored layer span`);
+    this.resources = collectResourceRequests(this.commands);
+  }
+
+  operations(): SemanticDrawOperation[] {
+    return this.commands.map((command, index) => {
+      const ownership = this.operationLayers[index];
+      const state = this.stateByLayer.get(ownership.layerId);
+      if (!state) throw new Error(`missing runtime layer state ${ownership.layerId}`);
+      return {
+        command,
+        layerId: ownership.layerId,
+        layerSlot: ownership.slot,
+        baseMatrix: [...state.baseMatrix] as SemanticDrawOperation["baseMatrix"],
+        visible: state.visible,
+        transform: { ...state.transform },
+        commandSlot: index,
+        commandVisible: this.commandVisible[index],
+        commandTransform: { ...this.commandTransforms[index] },
+      };
+    });
+  }
+
+  resourceRequests(): SemanticResourceKey[] {
+    return this.resources.map((resource) => ({ ...resource }));
+  }
+
+  applyLayerPatches(patches: SemanticLayerPatch[]): void {
+    for (const patch of patches) {
+      const state = this.stateByLayer.get(patch.layer_id);
+      if (!state) throw new Error(`unknown layer patch ${patch.layer_id}`);
+      if (patch.render_mask != null) state.visible = patch.render_mask;
+      if (patch.transform != null) state.transform = { ...patch.transform };
+    }
+  }
+
+  applyCommandPatches(patches: SemanticCommandStatePatch[]): void {
+    for (const patch of patches) {
+      if (!Number.isInteger(patch.slot) || patch.slot < 0 || patch.slot >= this.commands.length) throw new Error(`invalid command slot ${patch.slot}`);
+      if (patch.render_mask != null) this.commandVisible[patch.slot] = patch.render_mask;
+      if (patch.transform != null) this.commandTransforms[patch.slot] = { ...patch.transform };
+    }
+  }
+}
+
+export function semanticCommandPlanFromCoreSnapshot(snapshot: {
+  revisions: { layer_table: number } & Record<string, number>;
+  layer_table: SemanticCommandPlanInput["layerTable"];
+  layer_sources: Array<{ id: string; matrix: [number, number, number, number, number, number] }>;
+  commands: SemanticCommandPlanInput["layerCommands"];
+  semantic_commands: SemanticCommand[];
+  command_states: NonNullable<SemanticCommandPlanInput["commandStates"]>;
+}): SemanticCommandPlan {
+  return new SemanticCommandPlan({
+    layerTableRevision: snapshot.revisions.layer_table,
+    layerTable: snapshot.layer_table,
+    layerSources: snapshot.layer_sources.map((layer) => ({ layer_id: layer.id, matrix: layer.matrix })),
+    layerCommands: snapshot.commands,
+    semanticCommands: snapshot.semantic_commands,
+    commandStates: snapshot.command_states,
+  });
+}
+
+export type CoreSceneDumpInput = {
+  revisions: { layer_table: number } & Record<string, number>;
+  layer_table: SemanticCommandPlanInput["layerTable"];
+  layers: Array<{
+    layer_id: string;
+    matrix: [number, number, number, number, number, number];
+    render_mask: boolean;
+    commands: SemanticCommand[];
+  }>;
+  command_states: NonNullable<SemanticCommandPlanInput["commandStates"]>;
+};
+
+/** Adapts the native/server debug dump to the exact same immutable browser
+ * command plan used by a live WASM Scene. This is intentionally strict so a
+ * dump cannot silently reorder authored layers or command ownership. */
+export function semanticCommandPlanFromCoreDump(dump: CoreSceneDumpInput): SemanticCommandPlan {
+  const layerById = new Map(dump.layers.map((layer) => [layer.layer_id, layer] as const));
+  const semanticCommands: SemanticCommand[] = [];
+  const layerCommands: SemanticCommandPlanInput["layerCommands"] = [];
+  const layerSources: SemanticCommandPlanInput["layerSources"] = [];
+  for (const entry of [...dump.layer_table].sort((left, right) => left.slot - right.slot)) {
+    const layer = layerById.get(entry.layer_id);
+    if (!layer) throw new Error(`core dump missing layer ${entry.layer_id}`);
+    const commandStart = semanticCommands.length;
+    semanticCommands.push(...layer.commands);
+    layerSources.push({ layer_id: layer.layer_id, matrix: layer.matrix });
+    layerCommands.push({
+      layer_id: layer.layer_id,
+      render_mask: layer.render_mask,
+      transform: { dx: 0, dy: 0 },
+      command_start: commandStart,
+      command_count: layer.commands.length,
+    });
+  }
+  if (layerById.size !== dump.layer_table.length) throw new Error("core dump contains layers outside the layer table");
+  return new SemanticCommandPlan({
+    layerTableRevision: dump.revisions.layer_table,
+    layerTable: dump.layer_table,
+    layerSources,
+    layerCommands,
+    semanticCommands,
+    commandStates: dump.command_states,
+  });
+}
+
+function collectResourceRequests(commands: SemanticCommand[]): SemanticResourceKey[] {
+  const deduplicated = new Map<string, SemanticResourceKey>();
+  for (const command of commands) {
+    const resource = commandResource(command.payload);
+    if (!resource) continue;
+    deduplicated.set(`${resource.namespace}\0${resource.key}`, resource);
+    if (command.payload.kind === "image") {
+      const mask = asResourceKey(command.payload.alpha_mask);
+      if (mask) deduplicated.set(`${mask.namespace}\0${mask.key}`, mask);
+    }
+  }
+  return [...deduplicated.values()].map((resource) => ({ ...resource }));
+}
+
+function commandResource(payload: SemanticCommand["payload"]): SemanticResourceKey | null {
+  if (payload.kind === "image") return asResourceKey(payload.resource);
+  if (payload.kind !== "shape") return null;
+  const primitive = payload.primitive;
+  if (!primitive || typeof primitive !== "object" || Array.isArray(primitive)) return null;
+  const assetMask = (primitive as Record<string, unknown>).asset_mask;
+  if (!assetMask || typeof assetMask !== "object" || Array.isArray(assetMask)) return null;
+  return asResourceKey((assetMask as Record<string, unknown>).resource);
+}
+
+function asResourceKey(value: unknown): SemanticResourceKey | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const { namespace, key } = value as Record<string, unknown>;
+  return typeof namespace === "string" && typeof key === "string" ? { namespace, key } : null;
+}

package/src/gpu/semanticTextGlyphBridge.ts

@@ -0,0 +1,35 @@
+import type { GlyphInstance } from "../types/glyph.js";
+import { buildSdfGlyphInstanceVertices } from "./webglSdfGlyphPipeline.js";
+import type { SemanticDrawOperation } from "./semanticCommandPlanner.js";
+
+export function compileSemanticTextGlyphBatches(
+  instances: GlyphInstance[],
+  textOperations: SemanticDrawOperation[]
+): Map<string, Float32Array> {
+  const result = new Map<string, Float32Array>();
+  for (const operation of textOperations) {
+    if (operation.command.payload.kind !== "text") throw new Error(`non-text glyph bridge operation ${operation.command.id}`);
+    const commandInstances = instances.filter((instance) => instance.layerId === operation.command.id);
+    const clips = operation.command.clip == null
+      ? new Map<string, [[number, number], [number, number], [number, number], [number, number]]>()
+      : new Map([[operation.command.id, transformClip(operation.command.clip, operation.baseMatrix, operation.command.id)]]);
+    result.set(
+      operation.command.id,
+      buildSdfGlyphInstanceVertices(
+        commandInstances,
+        new Map([[operation.command.id, operation.layerSlot]]),
+        clips,
+        new Map([[operation.command.id, operation.commandSlot]])
+      )
+    );
+  }
+  return result;
+}
+
+function transformClip(value: unknown, matrix: [number, number, number, number, number, number], commandId: string): [[number, number], [number, number], [number, number], [number, number]] {
+  if (!Array.isArray(value) || value.length !== 4 || value.some((point) => !Array.isArray(point) || point.length !== 2)) throw new Error(`invalid text clip ${commandId}`);
+  return value.map((point) => [
+    matrix[0] * Number(point[0]) + matrix[2] * Number(point[1]) + matrix[4],
+    matrix[1] * Number(point[0]) + matrix[3] * Number(point[1]) + matrix[5],
+  ]) as [[number, number], [number, number], [number, number], [number, number]];
+}