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

package/src/telemetry/rendererTelemetry.ts

@@ -0,0 +1,358 @@
+export type TelemetryLevel = "off" | "summary" | "trace";
+
+const MAX_TRACE_SAMPLES = 240;
+
+export type RendererTelemetrySample = {
+  frameId: number;
+  gpuEpoch: number;
+  timingsMs: Record<string, number | null>;
+  workload: Record<string, number>;
+  recovery: { contextLosses: number; restoreMs: number | null; [key: string]: number | null };
+  [key: string]: unknown;
+};
+
+export type TelemetryDistribution = {
+  p50: number;
+  p95: number;
+  max: number;
+  samples: number;
+};
+
+export type RendererTelemetrySnapshot = {
+  schemaVersion: 1;
+  level: Exclude<TelemetryLevel, "off">;
+  last: RendererTelemetrySample;
+  summary: Record<string, TelemetryDistribution>;
+  recordedFrames: number;
+  droppedFrames: number;
+  samples?: RendererTelemetrySample[];
+};
+
+export class RendererTelemetry {
+  private readonly level: TelemetryLevel;
+  private readonly maxSamples: number;
+  private readonly summaryEvery: number;
+  private readonly samples: RendererTelemetrySample[] = [];
+  private readonly timingValues = new Map<string, number[]>();
+  private last: RendererTelemetrySample | null = null;
+  private recordedFrames = 0;
+  private droppedFrames = 0;
+  private cachedSummary: Record<string, TelemetryDistribution> = {};
+
+  constructor(options: { level?: TelemetryLevel; maxSamples?: number; summaryEvery?: number } = {}) {
+    this.level = options.level ?? "summary";
+    const requestedSamples = options.maxSamples ?? MAX_TRACE_SAMPLES;
+    this.maxSamples = Number.isFinite(requestedSamples)
+      ? Math.min(MAX_TRACE_SAMPLES, Math.max(1, Math.trunc(requestedSamples)))
+      : MAX_TRACE_SAMPLES;
+    this.summaryEvery = Math.max(1, options.summaryEvery ?? 30);
+  }
+
+  record(sample: RendererTelemetrySample): void {
+    if (this.level === "off") return;
+    assertTelemetryPrivacy(sample);
+    const sanitized = structuredClone(sample);
+    this.last = sanitized;
+    this.recordedFrames += 1;
+    for (const [name, value] of Object.entries(sample.timingsMs)) {
+      if (value == null || !Number.isFinite(value)) continue;
+      const values = this.timingValues.get(name) ?? [];
+      values.push(value);
+      if (values.length > this.maxSamples) values.splice(0, values.length - this.maxSamples);
+      this.timingValues.set(name, values);
+    }
+    if (this.level === "trace") {
+      this.samples.push(sanitized);
+      if (this.samples.length > this.maxSamples) {
+        this.droppedFrames += this.samples.length - this.maxSamples;
+        this.samples.splice(0, this.samples.length - this.maxSamples);
+      }
+    }
+    if (this.recordedFrames % this.summaryEvery === 0 || Object.keys(this.cachedSummary).length === 0) {
+      this.cachedSummary = summarize(this.timingValues);
+    }
+  }
+
+  snapshot(): RendererTelemetrySnapshot | null {
+    if (this.level === "off" || !this.last) return null;
+    const snapshot: RendererTelemetrySnapshot = {
+      schemaVersion: 1,
+      level: this.level,
+      last: structuredClone(this.last),
+      summary: structuredClone(summarize(this.timingValues)),
+      recordedFrames: this.recordedFrames,
+      droppedFrames: this.droppedFrames,
+    };
+    if (this.level === "trace") snapshot.samples = structuredClone(this.samples);
+    assertTelemetryPrivacy(snapshot);
+    return snapshot;
+  }
+
+  stats(): { level: TelemetryLevel; recordedFrames: number; retainedSamples: number; droppedFrames: number } {
+    return {
+      level: this.level,
+      recordedFrames: this.recordedFrames,
+      retainedSamples: this.samples.length,
+      droppedFrames: this.droppedFrames,
+    };
+  }
+}
+
+export type RendererTelemetryOptions = {
+  level?: TelemetryLevel;
+  maxSamples?: number;
+  summaryEvery?: number;
+};
+
+export type RendererAtlasSummary = {
+  backend: "edt" | "analytic";
+  pages: number;
+  glyphs: number;
+  missingGlyphs: number;
+  generation: {
+    glyphs: number;
+    pixels: number;
+    glyphMs: number;
+    faceLoadMs: number;
+  };
+  cache: {
+    hits: number;
+    misses: number;
+    generations: number;
+    bytes: number;
+    sessionHits: number;
+    persistentHits: number;
+    persistentMisses: number;
+    persistentWritesQueued: number;
+    pinnedPages: number;
+    pageEvictions: number;
+  } | null;
+};
+
+export type RendererGpuSummary = {
+  drawCalls: number;
+  geometryBuilds: number;
+  vertexBytes: number;
+  textureUploads: number;
+  textureBytes: number;
+  stateUploadBytes: number;
+  maskUploadBytes: number;
+  glyphGeometryBuilds: number;
+  isolationBegins: number;
+  isolationComposites: number;
+  isolationTargetAllocations: number;
+  isolationTextureBytes: number;
+};
+
+export type RendererUploadSummary = {
+  stateUploadBytes: number;
+  maskUploadBytes: number;
+  commandMaskUploadBytes: number;
+  commandStateUploadBytes: number;
+};
+
+export type RendererRestoreUploadSummary = {
+  atlasUploadBytes: number;
+  atlasUploadRects: number;
+  textureUploads: number;
+  textureBytes: number;
+};
+
+export type RendererRuntimeSnapshot = {
+  schemaVersion: 1;
+  state: "ready" | "context-lost" | "destroyed";
+  gpuEpoch: number;
+  frames: number;
+  bootstrap: {
+    textCommands: number;
+    glyphInstances: number;
+    atlasUploadBytes: number;
+    atlasUploadRects: number;
+  };
+  atlas: RendererAtlasSummary;
+  lastGpu: RendererGpuSummary | null;
+  updates: RendererUploadSummary;
+  recovery: {
+    contextLosses: number;
+    contextRestores: number;
+    restoreFailures: number;
+    lastRestoreMs: number | null;
+    lastRestoreUploads: RendererRestoreUploadSummary | null;
+  };
+  telemetry: RendererTelemetrySnapshot | null;
+};
+
+/** Tracks aggregate rendering health without retaining source text, stable ids,
+ * resource URLs, font names, or player data. */
+export class RendererRuntimeTelemetry {
+  private readonly telemetry: RendererTelemetry;
+  private readonly atlas: RendererAtlasSummary;
+  private readonly bootstrap: RendererRuntimeSnapshot["bootstrap"];
+  private runtimeState: RendererRuntimeSnapshot["state"] = "ready";
+  private gpuEpoch = 1;
+  private frames = 0;
+  private lastGpu: RendererGpuSummary | null = null;
+  private updates: RendererUploadSummary = {
+    stateUploadBytes: 0,
+    maskUploadBytes: 0,
+    commandMaskUploadBytes: 0,
+    commandStateUploadBytes: 0,
+  };
+  private contextLosses = 0;
+  private contextRestores = 0;
+  private restoreFailures = 0;
+  private lastRestoreMs: number | null = null;
+  private lastRestoreUploads: RendererRestoreUploadSummary | null = null;
+
+  constructor(
+    options: RendererTelemetryOptions,
+    atlas: RendererAtlasSummary,
+    bootstrap: RendererRuntimeSnapshot["bootstrap"],
+  ) {
+    this.telemetry = new RendererTelemetry(options);
+    this.atlas = structuredClone(atlas);
+    this.bootstrap = structuredClone(bootstrap);
+    assertTelemetryPrivacy(this.atlas);
+  }
+
+  state(): RendererRuntimeSnapshot["state"] {
+    return this.runtimeState;
+  }
+
+  recordDraw(metrics: RendererGpuSummary, submitCpuMs: number): void {
+    this.lastGpu = structuredClone(metrics);
+    this.frames += 1;
+    this.telemetry.record({
+      frameId: this.frames,
+      gpuEpoch: this.gpuEpoch,
+      timingsMs: {
+        gpuSubmitCpu: finiteOrNull(submitCpuMs),
+        gpuTime: null,
+        total: finiteOrNull(submitCpuMs),
+      },
+      workload: {
+        drawCalls: metrics.drawCalls,
+        vertexBytes: metrics.vertexBytes,
+        textureUploads: metrics.textureUploads,
+        textureBytes: metrics.textureBytes,
+        dirtyBytes: this.updates.stateUploadBytes
+          + this.updates.maskUploadBytes
+          + this.updates.commandMaskUploadBytes
+          + this.updates.commandStateUploadBytes,
+      },
+      recovery: {
+        contextLosses: this.contextLosses,
+        contextRestores: this.contextRestores,
+        restoreFailures: this.restoreFailures,
+        restoreMs: this.lastRestoreMs,
+      },
+    });
+  }
+
+  recordPatch(patch: Partial<RendererUploadSummary>): void {
+    for (const key of Object.keys(this.updates) as Array<keyof RendererUploadSummary>) {
+      this.updates[key] += patch[key] ?? 0;
+    }
+  }
+
+  markContextLost(): void {
+    if (this.runtimeState === "destroyed" || this.runtimeState === "context-lost") return;
+    this.runtimeState = "context-lost";
+    this.contextLosses += 1;
+  }
+
+  markContextRestored(restoreMs: number, uploads: RendererRestoreUploadSummary): void {
+    if (this.runtimeState === "destroyed") return;
+    this.runtimeState = "ready";
+    this.contextRestores += 1;
+    this.gpuEpoch += 1;
+    this.lastRestoreMs = finiteOrNull(restoreMs);
+    this.lastRestoreUploads = structuredClone(uploads);
+  }
+
+  markRestoreFailed(restoreMs: number): void {
+    if (this.runtimeState === "destroyed") return;
+    this.runtimeState = "context-lost";
+    this.restoreFailures += 1;
+    this.lastRestoreMs = finiteOrNull(restoreMs);
+  }
+
+  markDestroyed(): void {
+    this.runtimeState = "destroyed";
+  }
+
+  snapshot(): RendererRuntimeSnapshot {
+    const snapshot: RendererRuntimeSnapshot = {
+      schemaVersion: 1,
+      state: this.runtimeState,
+      gpuEpoch: this.gpuEpoch,
+      frames: this.frames,
+      bootstrap: structuredClone(this.bootstrap),
+      atlas: structuredClone(this.atlas),
+      lastGpu: structuredClone(this.lastGpu),
+      updates: structuredClone(this.updates),
+      recovery: {
+        contextLosses: this.contextLosses,
+        contextRestores: this.contextRestores,
+        restoreFailures: this.restoreFailures,
+        lastRestoreMs: this.lastRestoreMs,
+        lastRestoreUploads: structuredClone(this.lastRestoreUploads),
+      },
+      telemetry: this.telemetry.snapshot(),
+    };
+    assertTelemetryPrivacy(snapshot);
+    return snapshot;
+  }
+}
+
+export function normalizeGpuTimerResult(nanoseconds: number | undefined, disjoint: boolean): number | null {
+  if (disjoint || nanoseconds == null || !Number.isFinite(nanoseconds) || nanoseconds < 0) return null;
+  return nanoseconds / 1_000_000;
+}
+
+const FORBIDDEN_FIELDS = new Set([
+  "rawtext",
+  "sourcecontent",
+  "userid",
+  "profileseq",
+  "documentdigest",
+  "fontpath",
+  "fonturl",
+  "character",
+  "scalar",
+  "cluster",
+]);
+
+export function assertTelemetryPrivacy(value: unknown): void {
+  visit(value, "telemetry");
+}
+
+function visit(value: unknown, path: string): void {
+  if (value == null || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => visit(entry, `${path}[${index}]`));
+    return;
+  }
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    const normalized = key.replace(/[_-]/g, "").toLowerCase();
+    if (FORBIDDEN_FIELDS.has(normalized)) throw new Error(`forbidden telemetry field ${path}.${key}`);
+    visit(child, `${path}.${key}`);
+  }
+}
+
+function summarize(values: ReadonlyMap<string, readonly number[]>): Record<string, TelemetryDistribution> {
+  return Object.fromEntries([...values.entries()].map(([name, source]) => {
+    const sorted = [...source].sort((a, b) => a - b);
+    const quantile = (q: number) => sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * q))] ?? 0;
+    return [name, {
+      p50: quantile(0.5),
+      p95: quantile(0.95),
+      max: quantile(1),
+      samples: sorted.length,
+    }];
+  }));
+}
+
+function finiteOrNull(value: number): number | null {
+  return Number.isFinite(value) && value >= 0 ? value : null;
+}

package/src/types/atlas.ts

@@ -0,0 +1,80 @@
+import type { GlyphBatchRequest } from "../protocol.js";
+import type { GlyphRasterIdentity } from "../cache/glyphPersistentCache.js";
+
+export type GlyphRasterPlan = {
+  region: string;
+  family: string;
+  fontSourceHash: string;
+  schemaNamespace: string;
+  fontEngineFingerprint: string;
+  rasterContractId: string;
+  contractId: string;
+  backend: "edt" | "analytic";
+  supersample: number;
+  baseSize: number;
+  spread: number;
+  atlasWidth: number;
+  atlasHeight: number;
+  glyphs: Array<{ ch: string; glyphIndex: number; identity: GlyphRasterIdentity }>;
+  missing: string[];
+};
+
+export type AtlasPixelRect = { x: number; y: number; width: number; height: number };
+
+export type AtlasPlacement = {
+  page: number;
+  pageEpoch: number;
+  pixelRect: AtlasPixelRect;
+  u0: number;
+  v0: number;
+  u1: number;
+  v1: number;
+};
+
+export type AtlasGlyphRecord = {
+  key: string;
+  glyphIndex: number;
+  width: number;
+  height: number;
+  advance: number;
+  xOffset: number;
+  yOffset: number;
+  planeBearingX: number;
+  planeBearingY: number;
+  planeWidth: number;
+  planeHeight: number;
+  drawable: boolean;
+  pixels: Uint8Array;
+};
+
+export type AtlasGenerateRequest = GlyphBatchRequest & {
+  glyphs: Array<{ key: string; char: string; glyphIndex: number }>;
+};
+
+export type AtlasStats = {
+  pages: number;
+  pinnedPages: number;
+  glyphs: number;
+  atlasBytes: number;
+  evictions: number;
+  pageAllocations: number;
+  hardBudgetBytes: number;
+};
+
+export type AtlasResolveResult = {
+  leases: number[];
+  placements: Array<{ key: string; placement: AtlasPlacement }>;
+  missingKeys: string[];
+  generated: AtlasGlyphRecord[];
+  stats: AtlasStats;
+};
+
+export type AtlasPageUpdate = {
+  page: number;
+  pageWidth: number;
+  pageEpoch: number;
+  revision: number;
+  fullUpload: boolean;
+  pixels: Uint8Array;
+  dirtyRects: Array<AtlasPixelRect & { pixels: Uint8Array }>;
+};

package/src/types/authoring.ts

@@ -0,0 +1,85 @@
+export type AuthoringElementId = number;
+
+export const AUTHORING_CHECKPOINT_SCHEMA = "allium.renderer-authoring-checkpoint/v1" as const;
+
+export type AuthoringCategory =
+  | "bondsHonors"
+  | "cardMembers"
+  | "collections"
+  | "generalBackgrounds"
+  | "generals"
+  | "honors"
+  | "others"
+  | "shapes"
+  | "stamps"
+  | "standMembers"
+  | "storyBackgrounds"
+  | "texts";
+
+export type AuthoringCommand =
+  | { kind: "create"; page: number; category: AuthoringCategory; element: Record<string, unknown> }
+  | { kind: "duplicate"; id: AuthoringElementId }
+  | { kind: "delete"; id: AuthoringElementId }
+  | {
+      kind: "set_transform";
+      id: AuthoringElementId;
+      position?: [number, number, number] | null;
+      scale?: [number, number, number] | null;
+      rotation?: [number, number, number, number] | null;
+    }
+  | { kind: "set_lock"; id: AuthoringElementId; lock: boolean }
+  | { kind: "set_visible"; id: AuthoringElementId; visible: boolean }
+  | { kind: "set_parameters"; id: AuthoringElementId; values: Record<string, unknown> }
+  | { kind: "change_layer"; id: AuthoringElementId; layer: number };
+
+export type AuthoringChangeKind = "inserted" | "updated" | "removed";
+
+export type AuthoringElementChange = {
+  id: AuthoringElementId;
+  page: number;
+  category: AuthoringCategory;
+  kind: AuthoringChangeKind;
+  element: Record<string, unknown> | null;
+};
+
+export type AuthoringSelection = {
+  id: AuthoringElementId;
+  page: number;
+  category: AuthoringCategory;
+  index: number;
+  element: Record<string, unknown>;
+};
+
+export type AuthoringDelta = {
+  revision: number;
+  changes: AuthoringElementChange[];
+  canUndo: boolean;
+  canRedo: boolean;
+  selectedId: AuthoringElementId | null;
+  selected: AuthoringSelection | null;
+  pageChanges: AuthoringPageChange[];
+};
+
+export type AuthoringPageChangeKind = "inserted" | "removed" | "moved";
+
+export type AuthoringPageChange = {
+  kind: AuthoringPageChangeKind;
+  page: number;
+  fromPage: number | null;
+};
+
+export type GameProfileDocument = {
+  userCustomProfileCards: Array<Record<string, unknown>>;
+};
+
+/** Opaque renderer-owned history payload. Callers may persist it but must not edit its internals. */
+export type AuthoringCheckpoint = {
+  schema: typeof AUTHORING_CHECKPOINT_SCHEMA;
+  document: GameProfileDocument;
+  ids: unknown[];
+  nextId: number;
+  revision: number;
+  undo: unknown[];
+  redo: unknown[];
+  selectedId: AuthoringElementId | null;
+};

package/src/types/core.ts

@@ -0,0 +1,110 @@
+export type StableId = string;
+
+export type CoreControlBinding =
+  | { kind: "tab_option"; control_id: StableId; value: string }
+  | { kind: "scroll_content"; control_id: StableId }
+  | { kind: "scroll_thumb"; control_id: StableId }
+  | { kind: "scroll_viewport"; control_id: StableId };
+
+export type CoreLayerPatch = {
+  layer_id: StableId;
+  render_mask: boolean | null;
+  transform: { dx: number; dy: number } | null;
+};
+
+export type CoreCommandPatch = {
+  command_id: StableId;
+  slot: number;
+  render_mask: boolean | null;
+  transform: { dx: number; dy: number } | null;
+};
+
+export type CoreSceneDelta = {
+  schema_major: number;
+  schema_minor: number;
+  scene_id: StableId;
+  base_revision: number;
+  revision: number;
+  tick: number;
+  dirty: {
+    mask: boolean;
+    transform: boolean;
+    material: boolean;
+    layout: boolean;
+    command: boolean;
+    atlas: boolean;
+    control: boolean;
+  };
+  patches: CoreLayerPatch[];
+  command_patches: CoreCommandPatch[];
+  error?: string;
+};
+
+export type CoreInteractionRegion = {
+  id: StableId;
+  layer_id: StableId;
+  role: string;
+  bounds: { x: number; y: number; width: number; height: number };
+  quad: Array<[number, number]>;
+  matrix: [number, number, number, number, number, number];
+  hit_geometry: Array<[number, number]>;
+  clip: Array<[number, number]> | null;
+  control_bindings: CoreControlBinding[];
+  resolved_data: Record<string, unknown>;
+  capabilities: string[];
+  render_mask: boolean;
+};
+
+export type CoreLayerTableEntry = {
+  layer_id: StableId;
+  parent_id: StableId | null;
+  slot: number;
+  subtree_start: number;
+  subtree_end: number;
+};
+
+export type CoreSceneDump = {
+  schema: "allium.scene-dump";
+  schema_major: number;
+  schema_minor: number;
+  coordinate_space: "card-device-v1";
+  scene_id: StableId;
+  tick: number;
+  revisions: Record<string, number>;
+  layer_table: CoreLayerTableEntry[];
+  layer_tree: Array<[StableId, StableId | null]>;
+  layers: Array<Record<string, unknown>>;
+  interaction_regions: CoreInteractionRegion[];
+  component_controls: Array<Record<string, unknown>>;
+  command_states: Array<Record<string, unknown>>;
+  telemetry: Record<string, number>;
+  error?: string;
+};
+
+export type CoreSceneCreateResponse = {
+  handle: number;
+  layer_bindings: Array<{ source_key: string; layer_id: StableId }>;
+  snapshot: {
+    schema_major: number;
+    schema_minor: number;
+    scene_id: StableId;
+    revisions: Record<string, number>;
+    layer_table: CoreLayerTableEntry[];
+    layer_sources: Array<{
+      id: StableId;
+      matrix: [number, number, number, number, number, number];
+    } & Record<string, unknown>>;
+    commands: Array<{
+      layer_id: StableId;
+      render_mask: boolean;
+      transform: { dx: number; dy: number };
+      command_start: number;
+      command_count: number;
+    }>;
+    semantic_commands: Array<Record<string, unknown>>;
+    interaction_regions: CoreInteractionRegion[];
+    component_controls: Array<Record<string, unknown>>;
+    command_states: Array<Record<string, unknown>>;
+  };
+  error?: string;
+};

package/src/types/freeType.ts

@@ -0,0 +1,63 @@
+export type FreeTypeGlyph = {
+  key: string;
+  region: string;
+  family: string;
+  font_source_hash: string;
+  ch: string;
+  glyph_index: number;
+  width: number;
+  height: number;
+  bearing_x: number;
+  bearing_y: number;
+  x_offset: number;
+  y_offset: number;
+  advance: number;
+  plane_bearing_x: number;
+  plane_bearing_y: number;
+  plane_width: number;
+  plane_height: number;
+  drawable: boolean;
+  pixels?: number[] | Uint8Array;
+  pixels_base64?: string;
+};
+
+export type FreeTypeGlyphMapBatch = {
+  region: string;
+  family: string;
+  font_source_hash: string;
+  glyphs: Array<{ ch: string; glyph_index: number }>;
+  missing: string[];
+  error?: string;
+};
+
+export type FreeTypeGlyphBatchPerf = {
+  total_ms: number;
+  face_load_ms: number;
+  glyph_total_ms: number;
+  glyph_count: number;
+  per_glyph_avg_ms: number;
+  total_pixel_count: number;
+  avg_pixels_per_glyph: number;
+};
+
+export type FreeTypeGlyphBatch = {
+  region: string;
+  family: string;
+  font_source_hash: string;
+  base_size: number;
+  spread: number;
+  glyphs: FreeTypeGlyph[];
+  missing: string[];
+  perf?: FreeTypeGlyphBatchPerf;
+  error?: string;
+};
+
+export function decodeFreeTypePixels(glyph: FreeTypeGlyph): Uint8Array {
+  if (glyph.pixels instanceof Uint8Array) return glyph.pixels;
+  if (Array.isArray(glyph.pixels)) return new Uint8Array(glyph.pixels);
+  if (!glyph.pixels_base64) return new Uint8Array(glyph.width * glyph.height);
+  const raw = atob(glyph.pixels_base64);
+  const pixels = new Uint8Array(raw.length);
+  for (let index = 0; index < raw.length; index += 1) pixels[index] = raw.charCodeAt(index);
+  return pixels;
+}