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

package/dist/cache/indexedDbGlyphRecordStore.js

@@ -0,0 +1,214 @@
+import { GLYPH_CACHE_SCHEMA, GlyphPersistentCache, } from "./glyphPersistentCache.js";
+const DATABASE_NAME = "sekai-custom-profile-sdk-glyph-cache-v1";
+const DATABASE_VERSION = 1;
+const GLYPH_STORE = "glyphs";
+const META_STORE = "meta";
+const TOTALS_KEY = "totals";
+export class IndexedDbGlyphRecordStore {
+    databaseName;
+    databasePromise = null;
+    constructor(databaseName = DATABASE_NAME) {
+        this.databaseName = databaseName;
+    }
+    async getMany(keys) {
+        if (keys.length === 0)
+            return [];
+        const database = await this.database();
+        const transaction = database.transaction(GLYPH_STORE, "readonly");
+        const store = transaction.objectStore(GLYPH_STORE);
+        const records = await Promise.all(keys.map((key) => request(store.get(key))));
+        await transactionDone(transaction);
+        return records.filter((record) => record != null);
+    }
+    async putMany(records, token) {
+        if (records.length === 0)
+            return true;
+        const database = await this.database();
+        const transaction = database.transaction([GLYPH_STORE, META_STORE], "readwrite", { durability: "relaxed" });
+        const glyphs = transaction.objectStore(GLYPH_STORE);
+        const meta = transaction.objectStore(META_STORE);
+        const totals = await readTotals(meta);
+        if (token && token.startedAtMs <= totals.lastClearMs) {
+            transaction.abort();
+            try {
+                await transactionDone(transaction);
+            }
+            catch { /* intentional abort */ }
+            return false;
+        }
+        for (const record of records) {
+            const existing = await request(glyphs.get(record.opaqueKey));
+            if (existing) {
+                totals.bytes -= existing.byteSize;
+            }
+            else {
+                totals.entries += 1;
+            }
+            totals.bytes += record.byteSize;
+            glyphs.put(record);
+        }
+        meta.put(totals);
+        await transactionDone(transaction);
+        return true;
+    }
+    async deleteMany(keys) {
+        if (keys.length === 0)
+            return;
+        const database = await this.database();
+        const transaction = database.transaction([GLYPH_STORE, META_STORE], "readwrite", { durability: "relaxed" });
+        const glyphs = transaction.objectStore(GLYPH_STORE);
+        const meta = transaction.objectStore(META_STORE);
+        const totals = await readTotals(meta);
+        for (const key of keys) {
+            const existing = await request(glyphs.get(key));
+            if (!existing)
+                continue;
+            glyphs.delete(key);
+            totals.entries -= 1;
+            totals.bytes -= existing.byteSize;
+        }
+        meta.put(normalizeTotals(totals));
+        await transactionDone(transaction);
+    }
+    async stats() {
+        const database = await this.database();
+        const transaction = database.transaction(META_STORE, "readonly");
+        const totals = await readTotals(transaction.objectStore(META_STORE));
+        await transactionDone(transaction);
+        return { entries: totals.entries, bytes: totals.bytes };
+    }
+    async trimLruTo(maxBytes, protectedKeys = new Set()) {
+        const database = await this.database();
+        const transaction = database.transaction([GLYPH_STORE, META_STORE], "readwrite", { durability: "relaxed" });
+        const glyphs = transaction.objectStore(GLYPH_STORE);
+        const meta = transaction.objectStore(META_STORE);
+        const totals = await readTotals(meta);
+        let evicted = 0;
+        if (totals.bytes > maxBytes) {
+            const index = glyphs.index("lastAccessDay");
+            await iterateCursor(index.openCursor(), (cursor) => {
+                if (totals.bytes <= maxBytes)
+                    return false;
+                const record = cursor.value;
+                if (!protectedKeys.has(record.opaqueKey)) {
+                    cursor.delete();
+                    totals.entries -= 1;
+                    totals.bytes -= record.byteSize;
+                    evicted += 1;
+                }
+                return true;
+            });
+        }
+        meta.put(normalizeTotals(totals));
+        await transactionDone(transaction);
+        return evicted;
+    }
+    async sweepBefore(lastAccessDayExclusive, maxRecords) {
+        const database = await this.database();
+        const transaction = database.transaction([GLYPH_STORE, META_STORE], "readwrite", { durability: "relaxed" });
+        const glyphs = transaction.objectStore(GLYPH_STORE);
+        const meta = transaction.objectStore(META_STORE);
+        const totals = await readTotals(meta);
+        let scanned = 0;
+        let deleted = 0;
+        await iterateCursor(glyphs.index("lastAccessDay").openCursor(), (cursor) => {
+            if (scanned >= maxRecords)
+                return false;
+            scanned += 1;
+            const record = cursor.value;
+            if (record.lastAccessDay >= lastAccessDayExclusive)
+                return false;
+            cursor.delete();
+            totals.entries -= 1;
+            totals.bytes -= record.byteSize;
+            deleted += 1;
+            return true;
+        });
+        meta.put(normalizeTotals(totals));
+        await transactionDone(transaction);
+        return { scanned, deleted };
+    }
+    async clear(clearedAtMs = Date.now()) {
+        const database = await this.database();
+        const transaction = database.transaction([GLYPH_STORE, META_STORE], "readwrite");
+        transaction.objectStore(GLYPH_STORE).clear();
+        const meta = transaction.objectStore(META_STORE);
+        const totals = await readTotals(meta);
+        meta.put({ key: TOTALS_KEY, entries: 0, bytes: 0, lastClearMs: Math.max(totals.lastClearMs, clearedAtMs) });
+        await transactionDone(transaction);
+    }
+    close() {
+        void this.databasePromise?.then((database) => database.close());
+        this.databasePromise = null;
+    }
+    database() {
+        if (typeof indexedDB === "undefined")
+            return Promise.reject(new Error("IndexedDB is unavailable"));
+        this.databasePromise ??= new Promise((resolve, reject) => {
+            const open = indexedDB.open(this.databaseName, DATABASE_VERSION);
+            open.onupgradeneeded = () => {
+                const database = open.result;
+                const glyphs = database.createObjectStore(GLYPH_STORE, { keyPath: "opaqueKey" });
+                glyphs.createIndex("lastAccessDay", "lastAccessDay");
+                database.createObjectStore(META_STORE, { keyPath: "key" });
+            };
+            open.onerror = () => reject(open.error ?? new Error("open IndexedDB glyph cache failed"));
+            open.onblocked = () => reject(new Error("IndexedDB glyph cache upgrade was blocked"));
+            open.onsuccess = () => {
+                open.result.onversionchange = () => open.result.close();
+                resolve(open.result);
+            };
+        });
+        return this.databasePromise;
+    }
+}
+export function createOriginGlyphPersistentCache(options = {}) {
+    return new GlyphPersistentCache({
+        mode: "origin",
+        store: new IndexedDbGlyphRecordStore(options.databaseName),
+        softBytes: options.softBytes,
+        hardBytes: options.hardBytes,
+        ttlDays: options.ttlDays,
+    });
+}
+export const GLYPH_PERSISTENT_CACHE_INFO = Object.freeze({
+    databaseName: DATABASE_NAME,
+    databaseVersion: DATABASE_VERSION,
+    schemaNamespace: GLYPH_CACHE_SCHEMA,
+});
+function readTotals(store) {
+    return request(store.get(TOTALS_KEY)).then((totals) => totals
+        ? { ...totals, lastClearMs: Number.isFinite(totals.lastClearMs) ? totals.lastClearMs : Number.NEGATIVE_INFINITY }
+        : { key: TOTALS_KEY, entries: 0, bytes: 0, lastClearMs: Number.NEGATIVE_INFINITY });
+}
+function normalizeTotals(totals) {
+    totals.entries = Math.max(0, totals.entries);
+    totals.bytes = Math.max(0, totals.bytes);
+    return totals;
+}
+function request(value) {
+    return new Promise((resolve, reject) => {
+        value.onsuccess = () => resolve(value.result);
+        value.onerror = () => reject(value.error ?? new Error("IndexedDB request failed"));
+    });
+}
+function transactionDone(transaction) {
+    return new Promise((resolve, reject) => {
+        transaction.oncomplete = () => resolve();
+        transaction.onerror = () => reject(transaction.error ?? new Error("IndexedDB transaction failed"));
+        transaction.onabort = () => reject(transaction.error ?? new Error("IndexedDB transaction aborted"));
+    });
+}
+function iterateCursor(cursorRequest, visit) {
+    return new Promise((resolve, reject) => {
+        cursorRequest.onerror = () => reject(cursorRequest.error ?? new Error("IndexedDB cursor failed"));
+        cursorRequest.onsuccess = () => {
+            const cursor = cursorRequest.result;
+            if (!cursor || !visit(cursor)) {
+                resolve();
+                return;
+            }
+            cursor.continue();
+        };
+    });
+}

package/dist/cache/sessionImageResourceCache.d.ts

@@ -0,0 +1,39 @@
+export type DecodedImageValue<T> = {
+    value: T;
+    bytes: number;
+};
+export type ImageResourceLease<T> = {
+    value: T;
+    release(): void;
+};
+export declare class SessionImageResourceCache<T> {
+    private readonly budget;
+    private readonly entries;
+    private readonly inflight;
+    private clock;
+    private totalBytes;
+    private loads;
+    private hits;
+    private evictions;
+    constructor(budget: {
+        softBytes: number;
+        hardBytes: number;
+        dispose?: (value: T) => void;
+    });
+    acquire(key: string, loader: (signal: AbortSignal) => Promise<DecodedImageValue<T>>, signal?: AbortSignal): Promise<ImageResourceLease<T>>;
+    stats(): {
+        entries: number;
+        bytes: number;
+        pinned: number;
+        loads: number;
+        hits: number;
+        evictions: number;
+    };
+    keys(): string[];
+    clear(): void;
+    private load;
+    private lease;
+    private trimSoft;
+    private evictUntil;
+    private remove;
+}

package/dist/cache/sessionImageResourceCache.js

@@ -0,0 +1,156 @@
+export class SessionImageResourceCache {
+    budget;
+    entries = new Map();
+    inflight = new Map();
+    clock = 0;
+    totalBytes = 0;
+    loads = 0;
+    hits = 0;
+    evictions = 0;
+    constructor(budget) {
+        if (!Number.isFinite(budget.softBytes) || !Number.isFinite(budget.hardBytes)
+            || budget.softBytes < 0 || budget.hardBytes <= 0 || budget.softBytes > budget.hardBytes) {
+            throw new Error("invalid image cache byte budget");
+        }
+        this.budget = budget;
+    }
+    async acquire(key, loader, signal = new AbortController().signal) {
+        if (signal.aborted)
+            throw abortReason(signal);
+        const cached = this.entries.get(key);
+        if (cached) {
+            this.hits += 1;
+            cached.refs += 1;
+            cached.touched = ++this.clock;
+            return this.lease(cached);
+        }
+        let pending = this.inflight.get(key);
+        if (pending) {
+            this.hits += 1;
+        }
+        else {
+            this.loads += 1;
+            const controller = new AbortController();
+            const created = {
+                controller,
+                waiters: 0,
+                settled: false,
+                promise: undefined,
+            };
+            created.promise = Promise.resolve().then(() => this.load(key, () => loader(controller.signal), created));
+            pending = created;
+            this.inflight.set(key, pending);
+            void pending.promise.finally(() => {
+                pending.settled = true;
+                if (this.inflight.get(key) === pending)
+                    this.inflight.delete(key);
+            }).catch(() => undefined);
+        }
+        pending.waiters += 1;
+        try {
+            const entry = await awaitWithAbort(pending.promise, signal);
+            entry.refs += 1;
+            entry.touched = ++this.clock;
+            return this.lease(entry);
+        }
+        finally {
+            pending.waiters = Math.max(0, pending.waiters - 1);
+            if (pending.waiters === 0 && !pending.settled) {
+                if (this.inflight.get(key) === pending)
+                    this.inflight.delete(key);
+                pending.controller.abort(new DOMException("No resource waiters remain", "AbortError"));
+            }
+            this.trimSoft();
+        }
+    }
+    stats() {
+        return {
+            entries: this.entries.size,
+            bytes: this.totalBytes,
+            pinned: [...this.entries.values()].filter((entry) => entry.refs > 0).length,
+            loads: this.loads,
+            hits: this.hits,
+            evictions: this.evictions,
+        };
+    }
+    keys() {
+        return [...this.entries.entries()]
+            .sort(([, left], [, right]) => left.touched - right.touched)
+            .map(([key]) => key);
+    }
+    clear() {
+        for (const [key, entry] of this.entries) {
+            if (entry.refs === 0)
+                this.remove(key, entry);
+        }
+    }
+    async load(key, loader, owner) {
+        const decoded = await loader();
+        if (this.inflight.get(key) !== owner) {
+            this.budget.dispose?.(decoded.value);
+            throw abortReason(owner.controller.signal);
+        }
+        if (!Number.isFinite(decoded.bytes) || !Number.isInteger(decoded.bytes) || decoded.bytes < 0) {
+            throw new Error(`invalid decoded image byte size ${decoded.bytes}`);
+        }
+        if (decoded.bytes > this.budget.hardBytes) {
+            throw new Error(`decoded image exceeds hard byte budget: ${decoded.bytes} > ${this.budget.hardBytes}`);
+        }
+        this.evictUntil(this.budget.hardBytes - decoded.bytes);
+        if (this.totalBytes + decoded.bytes > this.budget.hardBytes) {
+            throw new Error(`decoded image cache hard byte budget is pinned`);
+        }
+        const entry = { value: decoded.value, bytes: decoded.bytes, refs: 0, touched: ++this.clock };
+        this.entries.set(key, entry);
+        this.totalBytes += decoded.bytes;
+        return entry;
+    }
+    lease(entry) {
+        let released = false;
+        return {
+            value: entry.value,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                entry.refs = Math.max(0, entry.refs - 1);
+                entry.touched = ++this.clock;
+                this.trimSoft();
+            },
+        };
+    }
+    trimSoft() {
+        this.evictUntil(this.budget.softBytes);
+    }
+    evictUntil(targetBytes) {
+        if (this.totalBytes <= targetBytes)
+            return;
+        const candidates = [...this.entries.entries()]
+            .filter(([, entry]) => entry.refs === 0)
+            .sort(([, left], [, right]) => left.touched - right.touched);
+        for (const [key, entry] of candidates) {
+            if (this.totalBytes <= targetBytes)
+                break;
+            this.remove(key, entry);
+        }
+    }
+    remove(key, entry) {
+        if (!this.entries.delete(key))
+            return;
+        this.totalBytes -= entry.bytes;
+        this.evictions += 1;
+        this.budget.dispose?.(entry.value);
+    }
+}
+function awaitWithAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(abortReason(signal));
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(abortReason(signal));
+        signal.addEventListener("abort", abort, { once: true });
+        void promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}

package/dist/emscripten.d.ts

@@ -0,0 +1,11 @@
+export type EmscriptenModule = {
+    HEAPU8: Uint8Array;
+    HEAPU32: Uint32Array;
+    _malloc(size: number): number;
+    _free(pointer: number): void;
+    ccall(name: string, returnType: "number" | null, argumentTypes: Array<"number" | "string">, arguments_: Array<number | string>): number | null;
+};
+export type EmscriptenModuleFactory = (options?: {
+    locateFile?: (path: string) => string;
+    printErr?: (...values: unknown[]) => void;
+}) => Promise<EmscriptenModule>;

package/dist/emscripten.js

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

package/dist/fontProvider.d.ts

@@ -0,0 +1,36 @@
+export type FontRequest = {
+    region: string;
+    family: string;
+};
+export type ProvidedFont = {
+    bytes: ArrayBuffer | Uint8Array;
+};
+export type FontContext = {
+    signal: AbortSignal;
+};
+/** Resolves a demanded font family through arbitrary caller-owned logic. */
+export interface FontProvider {
+    provide(request: FontRequest, context: FontContext): Promise<ProvidedFont | null>;
+}
+export type FontProviderManagerOptions = {
+    provider: FontProvider;
+    concurrency?: number;
+};
+export type FontProviderStats = {
+    requested: number;
+    unique: number;
+    loaded: number;
+    bytes: number;
+    failures: number;
+    active: number;
+    peakActive: number;
+    resolveMs: number;
+};
+export declare class FontProviderManager {
+    private readonly provider;
+    private readonly concurrency;
+    private readonly counters;
+    constructor(options: FontProviderManagerOptions);
+    resolve(requests: readonly FontRequest[], signal?: AbortSignal): Promise<Map<string, ArrayBuffer>>;
+    stats(): FontProviderStats;
+}

package/dist/fontProvider.js

@@ -0,0 +1,84 @@
+export class FontProviderManager {
+    provider;
+    concurrency;
+    counters = {
+        requested: 0,
+        unique: 0,
+        loaded: 0,
+        bytes: 0,
+        failures: 0,
+        active: 0,
+        peakActive: 0,
+        resolveMs: 0,
+    };
+    constructor(options) {
+        if (!options.provider || typeof options.provider.provide !== "function") {
+            throw new Error("font provider is required");
+        }
+        const concurrency = options.concurrency ?? 4;
+        if (!Number.isInteger(concurrency) || concurrency <= 0) {
+            throw new Error("font concurrency must be a positive integer");
+        }
+        this.provider = options.provider;
+        this.concurrency = concurrency;
+    }
+    async resolve(requests, signal = new AbortController().signal) {
+        const started = performance.now();
+        const unique = [...new Map(requests.map((request) => [
+                `${request.region}\0${request.family}`,
+                request,
+            ])).values()];
+        this.counters.requested += requests.length;
+        this.counters.unique += unique.length;
+        const values = new Map();
+        let cursor = 0;
+        const worker = async () => {
+            while (cursor < unique.length) {
+                if (signal.aborted)
+                    throw abortReason(signal);
+                const request = unique[cursor++];
+                this.counters.active += 1;
+                this.counters.peakActive = Math.max(this.counters.peakActive, this.counters.active);
+                let provided;
+                try {
+                    provided = await this.provider.provide(request, { signal });
+                }
+                catch (error) {
+                    this.counters.failures += 1;
+                    throw error;
+                }
+                finally {
+                    this.counters.active -= 1;
+                }
+                const bytes = provided?.bytes;
+                if (!(bytes instanceof ArrayBuffer) && !(bytes instanceof Uint8Array)) {
+                    this.counters.failures += 1;
+                    throw new Error(`font provider returned no bytes for ${request.region}:${request.family}`);
+                }
+                const snapshot = bytes instanceof ArrayBuffer
+                    ? bytes.slice(0)
+                    : Uint8Array.from(bytes).buffer;
+                if (snapshot.byteLength === 0) {
+                    this.counters.failures += 1;
+                    throw new Error(`font provider returned an empty font for ${request.region}:${request.family}`);
+                }
+                this.counters.loaded += 1;
+                this.counters.bytes += snapshot.byteLength;
+                values.set(request.family, snapshot);
+            }
+        };
+        try {
+            await Promise.all(Array.from({ length: Math.min(this.concurrency, unique.length) }, worker));
+            return values;
+        }
+        finally {
+            this.counters.resolveMs += performance.now() - started;
+        }
+    }
+    stats() {
+        return { ...this.counters };
+    }
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}

package/dist/fontSdfAtlas.d.ts

@@ -0,0 +1,92 @@
+import { GlyphPersistentCache } from "./cache/glyphPersistentCache.js";
+import { RendererWorkerClient } from "./worker-client.js";
+import type { RendererWorkerStats } from "./protocol.js";
+import type { AtlasPageUpdate, AtlasStats } from "./types/atlas.js";
+export type GlyphRequest = {
+    region: string;
+    family: string;
+    fontSourceHash: string;
+    char: string;
+};
+export type FontSource = {
+    region: string;
+    family: string;
+    sourceHash: string;
+};
+export type GlyphInfo = {
+    key: string;
+    resourceId: string;
+    glyphIndex: number;
+    page: number;
+    pageEpoch: number;
+    region: string;
+    family: string;
+    fontSourceHash: string;
+    char: string;
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+    width: number;
+    height: number;
+    advance: number;
+    xOffset: number;
+    yOffset: number;
+    planeBearingX: number;
+    planeBearingY: number;
+    planeWidth: number;
+    planeHeight: number;
+    drawable: boolean;
+};
+export type SdfBackend = "edt" | "analytic";
+export type PersistentCacheSelection = "memory-only" | "origin";
+export type SdfAtlasPerf = {
+    backend: SdfBackend;
+    fontBatches: [];
+    totalGlyphMs: number;
+    totalFaceLoadMs: number;
+    totalGlyphCount: number;
+    totalPixelCount: number;
+    worker: RendererWorkerStats;
+    cache: {
+        hits: number;
+        misses: number;
+        generations: number;
+        bytes: number;
+        sessionHits: number;
+        persistentHits: number;
+        persistentMisses: number;
+        persistentWritesQueued: number;
+        pages: number;
+        pinnedPages: number;
+        pageEvictions: number;
+    };
+};
+export type SdfAtlas = {
+    width: number;
+    height: number;
+    depth: number;
+    baseSize: number;
+    spread: number;
+    glyphs: Map<string, GlyphInfo>;
+    missing: string[];
+    backend: "freetype-wasm";
+    sdfBackend: SdfBackend;
+    contractId: string;
+    fontEngineFingerprint: string;
+    perf: SdfAtlasPerf;
+    pageUpdates(revisions: ReadonlyMap<number, number>): Promise<AtlasPageUpdate[]>;
+    release(): Promise<void>;
+};
+export declare function glyphKey(region: string, fontSourceHash: string, family: string, char: string): string;
+export declare function buildSdfAtlas(fontSources: FontSource[], requests: GlyphRequest[], options: {
+    worker: RendererWorkerClient;
+    persistence?: PersistentCacheSelection;
+    persistentCache?: GlyphPersistentCache;
+}, supersample?: number, backend?: SdfBackend): Promise<SdfAtlas>;
+export declare function getPersistentGlyphCache(): GlyphPersistentCache;
+export declare function getSessionAtlasStats(): Array<{
+    contractId: string;
+    stats: AtlasStats;
+}>;
+export declare function disposeWorkerAtlasSessions(worker: RendererWorkerClient): void;