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

package/dist/resourceProvider.js

@@ -0,0 +1,41 @@
+export function profileResourceDescriptors(preparation) {
+    const resources = preparation.resources;
+    if (!Array.isArray(resources))
+        throw new Error("Profile preparation did not return a resource list");
+    return resources.map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new Error("Profile resource entry is invalid");
+        }
+        const request = entry;
+        const resource = request.resource;
+        const fallback = request.fallback;
+        if (!resource || typeof resource !== "object" || Array.isArray(resource)) {
+            throw new Error("Profile resource key is missing");
+        }
+        if (!fallback || typeof fallback !== "object" || Array.isArray(fallback)) {
+            throw new Error("Profile resource fallback metric is missing");
+        }
+        const { namespace, key } = resource;
+        const { width, height } = fallback;
+        if (typeof namespace !== "string" || typeof key !== "string" || typeof request.lookup_key !== "string") {
+            throw new Error("Profile resource identity is invalid");
+        }
+        if (!isMetric(width) || !isMetric(height))
+            throw new Error("Profile resource fallback metric is invalid");
+        const provenance = request.provenance;
+        if (provenance != null && (typeof provenance !== "object" || Array.isArray(provenance))) {
+            throw new Error("Profile resource provenance is invalid");
+        }
+        return {
+            id: `${namespace}\0${key}`,
+            namespace,
+            key,
+            role: request.lookup_key,
+            provenance: provenance == null ? {} : { ...provenance },
+            expectedSize: { width, height },
+        };
+    });
+}
+function isMetric(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}

package/dist/telemetry/rendererTelemetry.d.ts

@@ -0,0 +1,158 @@
+export type TelemetryLevel = "off" | "summary" | "trace";
+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 declare class RendererTelemetry {
+    private readonly level;
+    private readonly maxSamples;
+    private readonly summaryEvery;
+    private readonly samples;
+    private readonly timingValues;
+    private last;
+    private recordedFrames;
+    private droppedFrames;
+    private cachedSummary;
+    constructor(options?: {
+        level?: TelemetryLevel;
+        maxSamples?: number;
+        summaryEvery?: number;
+    });
+    record(sample: RendererTelemetrySample): void;
+    snapshot(): RendererTelemetrySnapshot | null;
+    stats(): {
+        level: TelemetryLevel;
+        recordedFrames: number;
+        retainedSamples: number;
+        droppedFrames: number;
+    };
+}
+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 declare class RendererRuntimeTelemetry {
+    private readonly telemetry;
+    private readonly atlas;
+    private readonly bootstrap;
+    private runtimeState;
+    private gpuEpoch;
+    private frames;
+    private lastGpu;
+    private updates;
+    private contextLosses;
+    private contextRestores;
+    private restoreFailures;
+    private lastRestoreMs;
+    private lastRestoreUploads;
+    constructor(options: RendererTelemetryOptions, atlas: RendererAtlasSummary, bootstrap: RendererRuntimeSnapshot["bootstrap"]);
+    state(): RendererRuntimeSnapshot["state"];
+    recordDraw(metrics: RendererGpuSummary, submitCpuMs: number): void;
+    recordPatch(patch: Partial<RendererUploadSummary>): void;
+    markContextLost(): void;
+    markContextRestored(restoreMs: number, uploads: RendererRestoreUploadSummary): void;
+    markRestoreFailed(restoreMs: number): void;
+    markDestroyed(): void;
+    snapshot(): RendererRuntimeSnapshot;
+}
+export declare function normalizeGpuTimerResult(nanoseconds: number | undefined, disjoint: boolean): number | null;
+export declare function assertTelemetryPrivacy(value: unknown): void;

package/dist/telemetry/rendererTelemetry.js

@@ -0,0 +1,232 @@
+const MAX_TRACE_SAMPLES = 240;
+export class RendererTelemetry {
+    level;
+    maxSamples;
+    summaryEvery;
+    samples = [];
+    timingValues = new Map();
+    last = null;
+    recordedFrames = 0;
+    droppedFrames = 0;
+    cachedSummary = {};
+    constructor(options = {}) {
+        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) {
+        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() {
+        if (this.level === "off" || !this.last)
+            return null;
+        const snapshot = {
+            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() {
+        return {
+            level: this.level,
+            recordedFrames: this.recordedFrames,
+            retainedSamples: this.samples.length,
+            droppedFrames: this.droppedFrames,
+        };
+    }
+}
+/** Tracks aggregate rendering health without retaining source text, stable ids,
+ * resource URLs, font names, or player data. */
+export class RendererRuntimeTelemetry {
+    telemetry;
+    atlas;
+    bootstrap;
+    runtimeState = "ready";
+    gpuEpoch = 1;
+    frames = 0;
+    lastGpu = null;
+    updates = {
+        stateUploadBytes: 0,
+        maskUploadBytes: 0,
+        commandMaskUploadBytes: 0,
+        commandStateUploadBytes: 0,
+    };
+    contextLosses = 0;
+    contextRestores = 0;
+    restoreFailures = 0;
+    lastRestoreMs = null;
+    lastRestoreUploads = null;
+    constructor(options, atlas, bootstrap) {
+        this.telemetry = new RendererTelemetry(options);
+        this.atlas = structuredClone(atlas);
+        this.bootstrap = structuredClone(bootstrap);
+        assertTelemetryPrivacy(this.atlas);
+    }
+    state() {
+        return this.runtimeState;
+    }
+    recordDraw(metrics, submitCpuMs) {
+        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) {
+        for (const key of Object.keys(this.updates)) {
+            this.updates[key] += patch[key] ?? 0;
+        }
+    }
+    markContextLost() {
+        if (this.runtimeState === "destroyed" || this.runtimeState === "context-lost")
+            return;
+        this.runtimeState = "context-lost";
+        this.contextLosses += 1;
+    }
+    markContextRestored(restoreMs, uploads) {
+        if (this.runtimeState === "destroyed")
+            return;
+        this.runtimeState = "ready";
+        this.contextRestores += 1;
+        this.gpuEpoch += 1;
+        this.lastRestoreMs = finiteOrNull(restoreMs);
+        this.lastRestoreUploads = structuredClone(uploads);
+    }
+    markRestoreFailed(restoreMs) {
+        if (this.runtimeState === "destroyed")
+            return;
+        this.runtimeState = "context-lost";
+        this.restoreFailures += 1;
+        this.lastRestoreMs = finiteOrNull(restoreMs);
+    }
+    markDestroyed() {
+        this.runtimeState = "destroyed";
+    }
+    snapshot() {
+        const snapshot = {
+            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, disjoint) {
+    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) {
+    visit(value, "telemetry");
+}
+function visit(value, path) {
+    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)) {
+        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) {
+    return Object.fromEntries([...values.entries()].map(([name, source]) => {
+        const sorted = [...source].sort((a, b) => a - b);
+        const quantile = (q) => 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) {
+    return Number.isFinite(value) && value >= 0 ? value : null;
+}

package/dist/third-party/freetype/FTL.txt

@@ -0,0 +1,169 @@
+                    The FreeType Project LICENSE
+                    ----------------------------
+
+                            2006-Jan-27
+
+                    Copyright 1996-2002, 2006 by
+          David Turner, Robert Wilhelm, and Werner Lemberg
+
+
+
+Introduction
+============
+
+  The FreeType  Project is distributed in  several archive packages;
+  some of them may contain, in addition to the FreeType font engine,
+  various tools and  contributions which rely on, or  relate to, the
+  FreeType Project.
+
+  This  license applies  to all  files found  in such  packages, and
+  which do not  fall under their own explicit  license.  The license
+  affects  thus  the  FreeType   font  engine,  the  test  programs,
+  documentation and makefiles, at the very least.
+
+  This  license   was  inspired  by  the  BSD,   Artistic,  and  IJG
+  (Independent JPEG  Group) licenses, which  all encourage inclusion
+  and  use of  free  software in  commercial  and freeware  products
+  alike.  As a consequence, its main points are that:
+
+    o We don't promise that this software works. However, we will be
+      interested in any kind of bug reports. (`as is' distribution)
+
+    o You can  use this software for whatever you  want, in parts or
+      full form, without having to pay us. (`royalty-free' usage)
+
+    o You may not pretend that  you wrote this software.  If you use
+      it, or  only parts of it,  in a program,  you must acknowledge
+      somewhere  in  your  documentation  that  you  have  used  the
+      FreeType code. (`credits')
+
+  We  specifically  permit  and  encourage  the  inclusion  of  this
+  software, with  or without modifications,  in commercial products.
+  We  disclaim  all warranties  covering  The  FreeType Project  and
+  assume no liability related to The FreeType Project.
+
+
+  Finally,  many  people  asked  us  for  a  preferred  form  for  a
+  credit/disclaimer to use in compliance with this license.  We thus
+  encourage you to use the following text:
+
+   """
+    Portions of this software are copyright © <year> The FreeType
+    Project (www.freetype.org).  All rights reserved.
+   """
+
+  Please replace <year> with the value from the FreeType version you
+  actually use.
+
+
+Legal Terms
+===========
+
+0. Definitions
+--------------
+
+  Throughout this license,  the terms `package', `FreeType Project',
+  and  `FreeType  archive' refer  to  the  set  of files  originally
+  distributed  by the  authors  (David Turner,  Robert Wilhelm,  and
+  Werner Lemberg) as the `FreeType Project', be they named as alpha,
+  beta or final release.
+
+  `You' refers to  the licensee, or person using  the project, where
+  `using' is a generic term including compiling the project's source
+  code as  well as linking it  to form a  `program' or `executable'.
+  This  program is  referred to  as  `a program  using the  FreeType
+  engine'.
+
+  This  license applies  to all  files distributed  in  the original
+  FreeType  Project,   including  all  source   code,  binaries  and
+  documentation,  unless  otherwise  stated   in  the  file  in  its
+  original, unmodified form as  distributed in the original archive.
+  If you are  unsure whether or not a particular  file is covered by
+  this license, you must contact us to verify this.
+
+  The FreeType  Project is copyright (C) 1996-2000  by David Turner,
+  Robert Wilhelm, and Werner Lemberg.  All rights reserved except as
+  specified below.
+
+1. No Warranty
+--------------
+
+  THE FREETYPE PROJECT  IS PROVIDED `AS IS' WITHOUT  WARRANTY OF ANY
+  KIND, EITHER  EXPRESS OR IMPLIED,  INCLUDING, BUT NOT  LIMITED TO,
+  WARRANTIES  OF  MERCHANTABILITY   AND  FITNESS  FOR  A  PARTICULAR
+  PURPOSE.  IN NO EVENT WILL ANY OF THE AUTHORS OR COPYRIGHT HOLDERS
+  BE LIABLE  FOR ANY DAMAGES CAUSED  BY THE USE OR  THE INABILITY TO
+  USE, OF THE FREETYPE PROJECT.
+
+2. Redistribution
+-----------------
+
+  This  license  grants  a  worldwide, royalty-free,  perpetual  and
+  irrevocable right  and license to use,  execute, perform, compile,
+  display,  copy,   create  derivative  works   of,  distribute  and
+  sublicense the  FreeType Project (in  both source and  object code
+  forms)  and  derivative works  thereof  for  any  purpose; and  to
+  authorize others  to exercise  some or all  of the  rights granted
+  herein, subject to the following conditions:
+
+    o Redistribution of  source code  must retain this  license file
+      (`FTL.TXT') unaltered; any  additions, deletions or changes to
+      the original  files must be clearly  indicated in accompanying
+      documentation.   The  copyright   notices  of  the  unaltered,
+      original  files must  be  preserved in  all  copies of  source
+      files.
+
+    o Redistribution in binary form must provide a  disclaimer  that
+      states  that  the software is based in part of the work of the
+      FreeType Team,  in  the  distribution  documentation.  We also
+      encourage you to put an URL to the FreeType web page  in  your
+      documentation, though this isn't mandatory.
+
+  These conditions  apply to any  software derived from or  based on
+  the FreeType Project,  not just the unmodified files.   If you use
+  our work, you  must acknowledge us.  However, no  fee need be paid
+  to us.
+
+3. Advertising
+--------------
+
+  Neither the  FreeType authors and  contributors nor you  shall use
+  the name of the  other for commercial, advertising, or promotional
+  purposes without specific prior written permission.
+
+  We suggest,  but do not require, that  you use one or  more of the
+  following phrases to refer  to this software in your documentation
+  or advertising  materials: `FreeType Project',  `FreeType Engine',
+  `FreeType library', or `FreeType Distribution'.
+
+  As  you have  not signed  this license,  you are  not  required to
+  accept  it.   However,  as  the FreeType  Project  is  copyrighted
+  material, only  this license, or  another one contracted  with the
+  authors, grants you  the right to use, distribute,  and modify it.
+  Therefore,  by  using,  distributing,  or modifying  the  FreeType
+  Project, you indicate that you understand and accept all the terms
+  of this license.
+
+4. Contacts
+-----------
+
+  There are two mailing lists related to FreeType:
+
+    o freetype@nongnu.org
+
+      Discusses general use and applications of FreeType, as well as
+      future and  wanted additions to the  library and distribution.
+      If  you are looking  for support,  start in  this list  if you
+      haven't found anything to help you in the documentation.
+
+    o freetype-devel@nongnu.org
+
+      Discusses bugs,  as well  as engine internals,  design issues,
+      specific licenses, porting, etc.
+
+  Our home page can be found at
+
+    https://www.freetype.org
+
+
+--- end of FTL.TXT ---

package/dist/types/atlas.d.ts

@@ -0,0 +1,90 @@
+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/dist/types/atlas.js

@@ -0,0 +1 @@
+export {};