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

package/dist/fontSdfAtlas.js

@@ -0,0 +1,296 @@
+import { GlyphPersistentCache, createPersistentGlyphRecord, } from "./cache/glyphPersistentCache.js";
+import { createOriginGlyphPersistentCache } from "./cache/indexedDbGlyphRecordStore.js";
+const engines = new WeakMap();
+const engineRegistry = new Map();
+let originPersistentCache = null;
+export function glyphKey(region, fontSourceHash, family, char) {
+    return `${region}\u0000${fontSourceHash}\u0000${family}\u0000${char}`;
+}
+export async function buildSdfAtlas(fontSources, requests, options, supersample, backend) {
+    validateFontSources(fontSources);
+    const sdfBackend = backend ?? (supersample != null && supersample <= 0 ? "analytic" : "edt");
+    const persistent = options.persistentCache ?? (options.persistence === "origin" ? getOriginPersistentCache() : new GlyphPersistentCache());
+    const uniqueRequests = deduplicateRequests(requests);
+    const plan = await planGlyphs(options.worker, fontSources, uniqueRequests, sdfBackend, supersample ?? 2);
+    const engine = await getEngine(options.worker, plan.contractId);
+    const planned = new Map(plan.glyphs.map((glyph) => [
+        glyphKey(glyph.region, glyph.fontSourceHash, glyph.family, glyph.ch),
+        glyph,
+    ]));
+    for (const request of uniqueRequests) {
+        const glyph = planned.get(requestKey(request));
+        if (glyph)
+            engine.charToGlyphIndex.set(requestKey(request), glyph.glyphIndex);
+        else
+            engine.missingChars.add(requestKey(request));
+    }
+    const resolved = uniqueRequests.flatMap((request) => {
+        const glyph = planned.get(requestKey(request));
+        return glyph ? [{ request, glyphIndex: glyph.glyphIndex, identity: glyph.identity }] : [];
+    });
+    const unique = new Map(resolved.map((value) => [value.identity.opaqueKey, value]));
+    const placementsBefore = new Map([...unique.keys()].flatMap((key) => {
+        const placement = engine.placements.get(key);
+        return placement ? [[key, placement]] : [];
+    }));
+    const identities = [...unique.values()].map((value) => value.identity);
+    const persisted = await persistent.getMany(identities);
+    const cached = [...persisted.values()].map(recordToAtlas);
+    for (const record of cached)
+        engine.metrics.set(record.key, withoutPixels(record));
+    const missing = [...unique.values()].filter((value) => !persisted.has(value.identity.opaqueKey));
+    const generate = generationGroups(fontSources, missing, plan.backend, plan.supersample);
+    const workerBefore = await options.worker.stats();
+    const result = await engine.atlas.resolve([...unique.keys()], cached, generate);
+    engine.latestStats = result.stats;
+    const placementByKey = new Map(result.placements.map((entry) => [entry.key, entry.placement]));
+    for (const [key, placement] of placementByKey) {
+        engine.placements.set(key, { page: placement.page, pageEpoch: placement.pageEpoch });
+    }
+    const sessionHitKeys = new Set([...unique.keys()].filter((key) => {
+        const before = placementsBefore.get(key);
+        const after = placementByKey.get(key);
+        return before != null && after != null && before.page === after.page && before.pageEpoch === after.pageEpoch;
+    }));
+    const sessionHits = sessionHitKeys.size;
+    const persistentHits = [...persisted.keys()].filter((key) => !sessionHitKeys.has(key)).length;
+    for (const record of result.generated)
+        engine.metrics.set(record.key, withoutPixels(record));
+    if (result.generated.length > 0) {
+        const writeEpoch = persistent.beginWrite();
+        const records = await Promise.all(result.generated.map((record) => {
+            const identity = unique.get(record.key)?.identity;
+            if (!identity)
+                throw new Error(`generated atlas resource has unknown identity ${record.key}`);
+            return createPersistentGlyphRecord(identity, record);
+        }));
+        void persistent.putMany(records, writeEpoch).catch(() => undefined);
+    }
+    const glyphs = new Map();
+    for (const value of resolved) {
+        const resourceId = value.identity.opaqueKey;
+        const placement = placementByKey.get(resourceId);
+        const metrics = engine.metrics.get(resourceId);
+        if (!placement || !metrics)
+            throw new Error(`WASM atlas omitted glyph resource ${resourceId}`);
+        glyphs.set(requestKey(value.request), {
+            key: requestKey(value.request),
+            resourceId,
+            glyphIndex: value.glyphIndex,
+            page: placement.page,
+            pageEpoch: placement.pageEpoch,
+            region: value.request.region,
+            family: value.request.family,
+            fontSourceHash: value.request.fontSourceHash,
+            char: value.request.char,
+            u0: placement.u0,
+            v0: placement.v0,
+            u1: placement.u1,
+            v1: placement.v1,
+            width: metrics.width,
+            height: metrics.height,
+            advance: metrics.advance,
+            xOffset: metrics.xOffset,
+            yOffset: metrics.yOffset,
+            planeBearingX: metrics.planeBearingX,
+            planeBearingY: metrics.planeBearingY,
+            planeWidth: metrics.planeWidth,
+            planeHeight: metrics.planeHeight,
+            drawable: metrics.drawable,
+        });
+    }
+    const workerAfter = await options.worker.stats();
+    let released = false;
+    return {
+        width: plan.atlasWidth,
+        height: plan.atlasHeight,
+        depth: result.stats.pages,
+        baseSize: plan.baseSize,
+        spread: plan.spread,
+        glyphs,
+        missing: uniqueRequests.filter((request) => engine.missingChars.has(requestKey(request))).map(requestKey),
+        backend: "freetype-wasm",
+        sdfBackend: plan.backend,
+        contractId: plan.contractId,
+        fontEngineFingerprint: plan.fontEngineFingerprint,
+        perf: {
+            backend: sdfBackend,
+            fontBatches: [],
+            totalGlyphMs: Math.max(0, workerAfter.wasmMs - workerBefore.wasmMs),
+            totalFaceLoadMs: 0,
+            totalGlyphCount: result.generated.length,
+            totalPixelCount: result.generated.reduce((sum, record) => sum + record.pixels.byteLength, 0),
+            worker: workerAfter,
+            cache: {
+                hits: sessionHits + persistentHits,
+                misses: unique.size - sessionHits - persistentHits,
+                generations: result.generated.length,
+                bytes: result.stats.atlasBytes,
+                sessionHits,
+                persistentHits,
+                persistentMisses: unique.size - sessionHits - persistentHits,
+                persistentWritesQueued: result.generated.length,
+                pages: result.stats.pages,
+                pinnedPages: result.stats.pinnedPages,
+                pageEvictions: result.stats.evictions,
+            },
+        },
+        pageUpdates: (revisions) => engine.atlas.pages(revisions),
+        release: async () => {
+            if (released)
+                return;
+            released = true;
+            await Promise.all(result.leases.map((lease) => engine.atlas.release(lease)));
+        },
+    };
+}
+export function getPersistentGlyphCache() {
+    return getOriginPersistentCache();
+}
+export function getSessionAtlasStats() {
+    return [...engineRegistry.values()].flatMap((sessions) => [...sessions]
+        .map((engine) => ({ contractId: engine.contractId, stats: engine.latestStats })));
+}
+export function disposeWorkerAtlasSessions(worker) {
+    engineRegistry.delete(worker);
+    engines.delete(worker);
+}
+async function getEngine(worker, contractId) {
+    let byContract = engines.get(worker);
+    if (!byContract) {
+        byContract = new Map();
+        engines.set(worker, byContract);
+    }
+    let pending = byContract.get(contractId);
+    if (!pending) {
+        pending = worker.createAtlas().then((atlas) => {
+            const engine = {
+                atlas,
+                contractId,
+                charToGlyphIndex: new Map(),
+                missingChars: new Set(),
+                metrics: new Map(),
+                placements: new Map(),
+                latestStats: atlas.initialStats,
+            };
+            let registered = engineRegistry.get(worker);
+            if (!registered) {
+                registered = new Set();
+                engineRegistry.set(worker, registered);
+            }
+            registered.add(engine);
+            return engine;
+        });
+        byContract.set(contractId, pending);
+    }
+    return pending;
+}
+async function planGlyphs(worker, fonts, requests, backend, supersample) {
+    const groups = new Map();
+    for (const font of fonts)
+        groups.set(fontSourceKey(font), { font, chars: [], seen: new Set() });
+    for (const request of requests) {
+        const group = groups.get(fontRequestKey(request));
+        if (!group || group.seen.has(request.char))
+            continue;
+        group.seen.add(request.char);
+        group.chars.push(request.char);
+    }
+    const activeGroups = [...groups.values()].filter((group) => group.chars.length > 0);
+    if (activeGroups.length === 0 && fonts[0])
+        activeGroups.push({ font: fonts[0], chars: [], seen: new Set() });
+    const plans = await Promise.all(activeGroups.map((group) => worker.planGlyphs({
+        region: group.font.region,
+        family: group.font.family,
+        sourceHash: group.font.sourceHash,
+        chars: group.chars,
+        backend,
+        supersample,
+    })));
+    const first = plans[0];
+    if (!first)
+        throw new Error("WASM glyph raster plan requires at least one glyph request");
+    for (const plan of plans) {
+        if (plan.contractId !== first.contractId
+            || plan.baseSize !== first.baseSize
+            || plan.spread !== first.spread
+            || plan.atlasWidth !== first.atlasWidth
+            || plan.atlasHeight !== first.atlasHeight)
+            throw new Error("WASM returned incompatible glyph raster plans for one atlas");
+    }
+    return {
+        ...first,
+        glyphs: plans.flatMap((plan) => plan.glyphs.map((glyph) => ({
+            ...glyph,
+            region: plan.region,
+            family: plan.family,
+            fontSourceHash: plan.fontSourceHash,
+        }))),
+    };
+}
+function generationGroups(fonts, missing, backend, supersample) {
+    const groups = new Map();
+    for (const value of missing) {
+        const font = fonts.find((candidate) => fontSourceKey(candidate) === fontRequestKey(value.request));
+        if (!font)
+            throw new Error(`font source missing for ${value.request.region}/${value.request.family}`);
+        const key = fontSourceKey(font);
+        let group = groups.get(key);
+        if (!group) {
+            group = { region: font.region, family: font.family, sourceHash: font.sourceHash, chars: [], backend, supersample, glyphs: [] };
+            groups.set(key, group);
+        }
+        group.chars.push(value.request.char);
+        group.glyphs.push({ key: value.identity.opaqueKey, char: value.request.char, glyphIndex: value.glyphIndex });
+    }
+    return [...groups.values()];
+}
+function recordToAtlas(record) {
+    return {
+        key: record.opaqueKey,
+        glyphIndex: 0,
+        width: record.width,
+        height: record.height,
+        advance: record.advance,
+        xOffset: record.xOffset,
+        yOffset: record.yOffset,
+        planeBearingX: record.planeBearingX,
+        planeBearingY: record.planeBearingY,
+        planeWidth: record.planeWidth,
+        planeHeight: record.planeHeight,
+        drawable: record.drawable,
+        pixels: new Uint8Array(record.pixels),
+    };
+}
+function withoutPixels(record) {
+    const { pixels: _, ...metrics } = record;
+    return metrics;
+}
+function getOriginPersistentCache() {
+    originPersistentCache ??= typeof indexedDB === "undefined" ? new GlyphPersistentCache() : createOriginGlyphPersistentCache();
+    return originPersistentCache;
+}
+function validateFontSources(fonts) {
+    for (const font of fonts) {
+        if (!font.region || !font.family)
+            throw new Error("font region/family must be non-empty");
+        if (!/^[0-9a-f]{64}$/i.test(font.sourceHash))
+            throw new Error(`font ${font.region}/${font.family} requires a full SHA-256 digest`);
+    }
+}
+function deduplicateRequests(requests) {
+    const result = new Map();
+    for (const request of requests)
+        if (request.char !== "\n" && request.char !== "\r" && !result.has(requestKey(request)))
+            result.set(requestKey(request), request);
+    return [...result.values()];
+}
+function fontSourceKey(source) {
+    return `${source.region}\u0000${source.sourceHash}\u0000${source.family}`;
+}
+function fontRequestKey(request) {
+    return `${request.region}\u0000${request.fontSourceHash}\u0000${request.family}`;
+}
+function requestKey(request) {
+    return glyphKey(request.region, request.fontSourceHash, request.family, request.char);
+}

package/dist/gpu/browserSemanticResources.d.ts

@@ -0,0 +1,64 @@
+import type { ResourceDescriptor, ResourceProvider } from "../resourceProvider.js";
+export type BrowserImageSource = {
+    source: TexImageSource;
+    width: number;
+    height: number;
+};
+export type BrowserSemanticResourceOptions = {
+    provider: ResourceProvider;
+    concurrency?: number;
+    decode?: (blob: Blob) => Promise<TexImageSource>;
+    softBytes?: number;
+    hardBytes?: number;
+};
+export type BrowserSemanticResourceSet = {
+    sources: Map<string, BrowserImageSource>;
+    availability: Map<string, boolean>;
+    release(): void;
+};
+export type ResourceProviderRuntimeStats = {
+    requested: number;
+    loaded: number;
+    failures: number;
+    cancellations: number;
+    encodedBytes: number;
+    resolveMs: number;
+    active: number;
+    queued: number;
+    limit: number;
+    peak: number;
+};
+/** The provider owns acquisition and persistent caching. This manager only
+ * schedules provider calls and retains bounded decoded session resources. */
+export declare class BrowserSemanticResourceManager {
+    private readonly provider;
+    private readonly decode;
+    private readonly scheduler;
+    private readonly cache;
+    private readonly providerCounters;
+    constructor(options: BrowserSemanticResourceOptions);
+    acquire(resources: ResourceDescriptor[], signal?: AbortSignal): Promise<BrowserSemanticResourceSet>;
+    stats(): {
+        provider: {
+            active: number;
+            queued: number;
+            limit: number;
+            peak: number;
+            requested: number;
+            loaded: number;
+            failures: number;
+            cancellations: number;
+            encodedBytes: number;
+            resolveMs: number;
+        };
+        entries: number;
+        bytes: number;
+        pinned: number;
+        loads: number;
+        hits: number;
+        evictions: number;
+    };
+    private load;
+    private resolveSource;
+}
+export declare function resourceIdentity(resource: Pick<ResourceDescriptor, "id">): string;

package/dist/gpu/browserSemanticResources.js

@@ -0,0 +1,232 @@
+import { SessionImageResourceCache } from "../cache/sessionImageResourceCache.js";
+/** The provider owns acquisition and persistent caching. This manager only
+ * schedules provider calls and retains bounded decoded session resources. */
+export class BrowserSemanticResourceManager {
+    provider;
+    decode;
+    scheduler;
+    cache;
+    providerCounters = {
+        requested: 0,
+        loaded: 0,
+        failures: 0,
+        cancellations: 0,
+        encodedBytes: 0,
+        resolveMs: 0,
+    };
+    constructor(options) {
+        if (!options.provider || typeof options.provider.provide !== "function") {
+            throw new Error("semantic resource provider is required");
+        }
+        this.provider = options.provider;
+        this.decode = options.decode ?? ((blob) => createImageBitmap(blob, {
+            premultiplyAlpha: "none",
+            colorSpaceConversion: "none",
+        }));
+        this.scheduler = new BoundedScheduler(options.concurrency ?? 8);
+        this.cache = new SessionImageResourceCache({
+            softBytes: options.softBytes ?? 64 * 1024 * 1024,
+            hardBytes: options.hardBytes ?? 96 * 1024 * 1024,
+            dispose: (value) => closeImageSource(value.image.source),
+        });
+    }
+    async acquire(resources, signal = new AbortController().signal) {
+        const unique = new Map(resources.map((resource) => [resourceIdentity(resource), resource]));
+        const leases = [];
+        try {
+            await Promise.all([...unique].map(async ([identity, resource]) => {
+                const cacheIdentity = this.provider.cacheIdentity?.(resource) ?? identity;
+                const lease = await this.cache.acquire(cacheIdentity, async (sharedSignal) => {
+                    const value = await this.load(resource, sharedSignal);
+                    return { value, bytes: decodedBytes(value.image) };
+                }, signal);
+                leases.push({ identity, lease });
+            }));
+        }
+        catch (error) {
+            for (const { lease } of leases)
+                lease.release();
+            throw error;
+        }
+        const sources = new Map(leases.map(({ identity, lease }) => [identity, lease.value.image]));
+        const availability = new Map(leases.map(({ identity, lease }) => [identity, lease.value.available]));
+        let released = false;
+        return {
+            sources,
+            availability,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                for (const { lease } of leases)
+                    lease.release();
+            },
+        };
+    }
+    stats() {
+        return {
+            ...this.cache.stats(),
+            provider: {
+                ...this.providerCounters,
+                ...this.scheduler.stats(),
+            },
+        };
+    }
+    async load(resource, signal) {
+        this.providerCounters.requested += 1;
+        const started = performance.now();
+        try {
+            const provided = await this.scheduler.run(() => this.provider.provide(resource, { signal }), signal);
+            if (signal.aborted)
+                throw abortReason(signal);
+            if (!provided)
+                throw new Error("provider returned no resource");
+            const image = await this.resolveSource(provided);
+            this.providerCounters.loaded += 1;
+            this.providerCounters.encodedBytes += providedByteLength(provided);
+            return { image, available: true };
+        }
+        catch (error) {
+            if (signal.aborted || isAbortError(error)) {
+                this.providerCounters.cancellations += 1;
+                throw error;
+            }
+            this.providerCounters.failures += 1;
+            warnMissingResource(resource, error);
+            return {
+                image: normalizeSource(await this.decode(transparentPngBlob())),
+                available: false,
+            };
+        }
+        finally {
+            this.providerCounters.resolveMs += Math.max(0, performance.now() - started);
+        }
+    }
+    async resolveSource(provided) {
+        const source = provided.source;
+        if (source instanceof Blob)
+            return normalizeSource(await this.decode(source));
+        if (source instanceof ArrayBuffer)
+            return normalizeSource(await this.decode(new Blob([source])));
+        if (ArrayBuffer.isView(source)) {
+            const view = new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+            const bytes = new Uint8Array(view.byteLength);
+            bytes.set(view);
+            return normalizeSource(await this.decode(new Blob([bytes])));
+        }
+        const dimensions = sourceDimensions(source);
+        if (!dimensions)
+            throw new Error("direct image source has no finite dimensions");
+        return { source, ...dimensions };
+    }
+}
+export function resourceIdentity(resource) {
+    if (!resource.id)
+        throw new Error("semantic resource stable id is required");
+    return resource.id;
+}
+class BoundedScheduler {
+    limit;
+    active = 0;
+    peak = 0;
+    queue = [];
+    constructor(limit) {
+        if (!Number.isInteger(limit) || limit <= 0)
+            throw new Error("semantic resource concurrency must be a positive integer");
+        this.limit = limit;
+    }
+    run(task, signal) {
+        return new Promise((resolve, reject) => {
+            const start = () => {
+                if (signal.aborted) {
+                    reject(abortReason(signal));
+                    this.drain();
+                    return;
+                }
+                this.active += 1;
+                this.peak = Math.max(this.peak, this.active);
+                void task().then(resolve, reject).finally(() => {
+                    this.active -= 1;
+                    this.drain();
+                });
+            };
+            this.queue.push(start);
+            this.drain();
+        });
+    }
+    stats() {
+        return { active: this.active, queued: this.queue.length, limit: this.limit, peak: this.peak };
+    }
+    drain() {
+        while (this.active < this.limit) {
+            const start = this.queue.shift();
+            if (!start)
+                return;
+            start();
+        }
+    }
+}
+function sourceDimensions(source) {
+    const value = source;
+    const width = firstPositiveDimension(value.videoWidth, value.naturalWidth, value.displayWidth, value.width);
+    const height = firstPositiveDimension(value.videoHeight, value.naturalHeight, value.displayHeight, value.height);
+    return width != null && height != null
+        ? { width, height }
+        : null;
+}
+function decodedBytes(source) {
+    return Math.max(0, Math.floor(source.width * source.height * 4));
+}
+function providedByteLength(provided) {
+    const source = provided.source;
+    if (source instanceof Blob)
+        return source.size;
+    if (source instanceof ArrayBuffer)
+        return source.byteLength;
+    if (ArrayBuffer.isView(source))
+        return source.byteLength;
+    return 0;
+}
+function normalizeSource(source) {
+    const dimensions = sourceDimensions(source);
+    if (!dimensions)
+        throw new Error("decoded image source has no finite dimensions");
+    return { source, ...dimensions };
+}
+function firstPositiveDimension(...values) {
+    for (const value of values) {
+        const dimension = numericDimension(value);
+        if (Number.isFinite(dimension) && dimension > 0)
+            return dimension;
+    }
+    return null;
+}
+function numericDimension(value) {
+    if (value && typeof value === "object") {
+        const animated = value;
+        const resolved = animated.animVal?.value ?? animated.baseVal?.value;
+        if (resolved != null)
+            return Number(resolved);
+    }
+    return Number(value);
+}
+function closeImageSource(source) {
+    const close = source.close;
+    if (typeof close === "function")
+        close.call(source);
+}
+function isAbortError(error) {
+    return error instanceof DOMException && error.name === "AbortError";
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+const TRANSPARENT_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYGBgAAAABQABpfZFQAAAAABJRU5ErkJggg==";
+function transparentPngBlob() {
+    const bytes = Uint8Array.from(atob(TRANSPARENT_PNG_BASE64), (value) => value.charCodeAt(0));
+    return new Blob([bytes], { type: "image/png" });
+}
+function warnMissingResource(resource, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    console.warn(`[sekai-custom-profile-sdk] semantic resource unavailable ${resource.namespace}/${resource.key} role=${resource.role}: ${reason}; using transparent placeholder`);
+}

package/dist/gpu/generalTextRenderPlacement.d.ts

@@ -0,0 +1,8 @@
+import type { GlyphInstance } from "../types/glyph.js";
+import type { SemanticDrawOperation } from "./semanticCommandPlanner.js";
+/**
+ * Applies General's measured draw anchors after the Rust TMP layout has
+ * finished. The returned instances retain the exact layout metrics and glyph
+ * relationships; only final local/device draw coordinates are translated.
+ */
+export declare function placeGeneralTextInstances(instances: readonly GlyphInstance[], operations: readonly SemanticDrawOperation[]): GlyphInstance[];