@typfolio/workers 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @typfolio/workers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-independent module-worker execution for `@typfolio/core`. The package provides a lazy bounded pool, FIFO scheduling, a finite queue, per-job `AbortSignal` cancellation, timeouts, worker replacement, incremental batches, and deterministic disposal.
+
+```ts
+import { createWorkerClient } from '@typfolio/workers';
+import wasmUrl from '@typfolio/wasm/compiler.wasm?url';
+
+const client = createWorkerClient({
+  compiler: { wasm: wasmUrl, fonts: ['/fonts/report.otf'] },
+  workerCount: 2,
+  queueLimit: 16,
+  timeoutMs: 30_000,
+});
+
+try {
+  const result = await client.compile(request, { signal });
+  // result.bytes is transferred from the worker without copying it again.
+} finally {
+  await client.dispose();
+}
+```
+
+Stream a large batch in completion order without retaining every PDF:
+
+```ts
+import { compileBatch } from '@typfolio/workers';
+
+for await (const outcome of compileBatch(client, jobs, { signal })) {
+  if (outcome.status === 'success') {
+    await upload(outcome.id, outcome.result.bytes);
+  }
+}
+```
+
+Use `collectBatch(client, jobs)` when the caller needs all outcomes in input order.
+
+The built-in factory creates a module worker from the packaged runtime. `workerFactory` is available for tests or hosts with custom worker construction. The client owns every worker returned by that factory and terminates it during hard cancellation, transport recovery, or disposal.
+
+## Semantics
+
+- Calls are snapshotted synchronously and compiled FIFO, with one active compile per worker.
+- Cancelling a waiting job removes only that job. Cancelling or timing out the active synchronous WASM call terminates its worker; the next queued job receives a fresh worker/compiler.
+- A Typst compilation error rejects that job but keeps the worker healthy. A malformed message or worker crash rejects the active job and replaces the worker lazily.
+- `queueLimit` counts waiting jobs, not the active compile. Timeouts include queue time.
+- `dispose()` is idempotent, rejects all unsettled work with `DISPOSED`, and terminates the owned worker.
+- Errors crossing the realm boundary become `TypfolioWorkerError` with stable `code`, `message`, and `diagnostics` fields.
+
+`fonts` takes `Uint8Array | string | URL`, as in `@typfolio/core`, and `createWorkerClient` stays synchronous. Give fonts as URLs and each worker fetches them itself while it initializes, so the font bytes never cross the worker boundary (bytes are structured-cloned into every worker). A `URL` is sent as its `href`; a string is resolved against the page URL on the client thread before it is sent, because inside a worker a relative string would resolve against the worker script. Without a page URL (for example in Node) a string must be absolute, otherwise `createWorkerClient` throws a `TypeError`. A font that cannot be fetched in the worker fails initialization: the job rejects with a `TypfolioWorkerError` whose `code` is `INITIALIZATION` and whose message names the URL.
+
+Worker transport accepts a WASM URL string, `ArrayBuffer`, `Uint8Array`, or compiled `WebAssembly.Module`. `Request` and `Response` are intentionally excluded because they are not consistently structured-cloneable across browsers. Asset bytes are copied once, on the client thread, when `compile` snapshots the request, so the caller's buffers stay intact and reusable. That private copy is then transferred to the worker (not cloned again), and the worker mounts it as received without copying it a third time. A `SharedArrayBuffer`-backed asset cannot be transferred and still travels by structured clone. `compileBatch` snapshots each job once and passes that snapshot straight to the client.
+
+The package uses Effect internally for interruptible jobs, timeout/abort races, scoped client disposal, and bounded completion-order batch streams. The public contract deliberately remains framework-neutral: consumers use Promises, `AbortSignal`, async iterables, and `TypfolioWorkerError`, without needing Effect in application code. The worker wire protocol and explicit `Worker.terminate()` slot recovery remain Typfolio-owned because hard cancellation must stop synchronous WASM.

package/dist/batch.d.ts

@@ -0,0 +1,8 @@
+import { type PdfBatchJob, type PdfBatchOptions, type PdfBatchOutcome, type PdfWorkerClient } from './types.js';
+/**
+ * Compiles a batch with at most `client.workerCount` submitted jobs at once.
+ * Events are yielded in completion order and results are not retained here.
+ */
+export declare function compileBatch<Id>(client: PdfWorkerClient, jobs: readonly PdfBatchJob<Id>[], options?: PdfBatchOptions<Id>): AsyncIterable<PdfBatchOutcome<Id>>;
+/** Collects batch events into input order. Prefer `compileBatch` for large outputs. */
+export declare function collectBatch<Id>(client: PdfWorkerClient, jobs: readonly PdfBatchJob<Id>[], options?: PdfBatchOptions<Id>): Promise<readonly PdfBatchOutcome<Id>[]>;

package/dist/batch.js

@@ -0,0 +1,94 @@
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+import { snapshotRequest } from './snapshot.js';
+import { TypfolioWorkerError, } from './types.js';
+function cancelled(job) {
+    return { id: job.id, index: job.index, status: 'cancelled' };
+}
+function normalizeError(error) {
+    return error instanceof TypfolioWorkerError
+        ? error
+        : new TypfolioWorkerError('WORKER', error instanceof Error ? error.message : String(error), [], { cause: error });
+}
+const run = Effect.fnUntraced(function* (client, job, batchSignal) {
+    if (batchSignal?.aborted)
+        return cancelled(job);
+    return yield* Effect.tryPromise({
+        try: effectSignal => {
+            const controller = new AbortController();
+            const abortFromEffect = () => controller.abort(effectSignal.reason);
+            const abortFromBatch = () => controller.abort(batchSignal?.reason);
+            effectSignal.addEventListener('abort', abortFromEffect, { once: true });
+            batchSignal?.addEventListener('abort', abortFromBatch, { once: true });
+            if (effectSignal.aborted)
+                abortFromEffect();
+            if (batchSignal?.aborted)
+                abortFromBatch();
+            return client.compile(job.request, {
+                signal: controller.signal,
+                timeoutMs: job.timeoutMs,
+            }).finally(() => {
+                effectSignal.removeEventListener('abort', abortFromEffect);
+                batchSignal?.removeEventListener('abort', abortFromBatch);
+            });
+        },
+        catch: normalizeError,
+    }).pipe(Effect.match({
+        onFailure: error => error.code === 'ABORTED'
+            ? cancelled(job)
+            : { id: job.id, index: job.index, status: 'error', error },
+        onSuccess: (result) => ({
+            id: job.id,
+            index: job.index,
+            status: 'success',
+            result,
+        }),
+    }));
+});
+function initialProgress(total) {
+    return { total, completed: 0, succeeded: 0, failed: 0, cancelled: 0 };
+}
+function advance(progress, outcome) {
+    return {
+        total: progress.total,
+        completed: progress.completed + 1,
+        succeeded: progress.succeeded + (outcome.status === 'success' ? 1 : 0),
+        failed: progress.failed + (outcome.status === 'error' ? 1 : 0),
+        cancelled: progress.cancelled + (outcome.status === 'cancelled' ? 1 : 0),
+        latestJobId: outcome.id,
+    };
+}
+/**
+ * Compiles a batch with at most `client.workerCount` submitted jobs at once.
+ * Events are yielded in completion order and results are not retained here.
+ */
+export function compileBatch(client, jobs, options = {}) {
+    const captured = jobs.map((job, index) => ({
+        id: job.id,
+        index,
+        request: snapshotRequest(job.request),
+        timeoutMs: job.timeoutMs,
+    }));
+    return (async function* stream() {
+        let progress = initialProgress(captured.length);
+        options.onProgress?.(progress);
+        const outcomes = Stream.fromIterable(captured).pipe(Stream.mapEffect(job => run(client, job, options.signal), {
+            concurrency: client.workerCount,
+            unordered: true,
+        }), Stream.tap(outcome => Effect.sync(() => {
+            progress = advance(progress, outcome);
+            options.onProgress?.(progress);
+            options.onItemSettled?.(outcome, progress);
+        })));
+        for await (const outcome of Stream.toAsyncIterable(outcomes)) {
+            yield outcome;
+        }
+    })();
+}
+/** Collects batch events into input order. Prefer `compileBatch` for large outputs. */
+export async function collectBatch(client, jobs, options = {}) {
+    const outcomes = new Array(jobs.length);
+    for await (const outcome of compileBatch(client, jobs, options))
+        outcomes[outcome.index] = outcome;
+    return outcomes;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { type CreateWorkerClientOptions, type PdfWorkerClient } from './types.js';
+export { TypfolioWorkerError, type CreateWorkerClientOptions, type PdfWorkerClient, type WorkerCompileOptions, type WorkerCompilerOptions, type WorkerErrorCode, type WorkerFontSource, type WorkerWasmSource, type PdfBatchJob, type PdfBatchOptions, type PdfBatchOutcome, type PdfBatchProgress, } from './types.js';
+export { collectBatch, compileBatch } from './batch.js';
+export declare function createWorkerClient(options: CreateWorkerClientOptions): PdfWorkerClient;

package/dist/index.js

@@ -0,0 +1,304 @@
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import { decodeRuntimeMessage, protocolVersion } from './protocol.js';
+import { isSnapshot, snapshotRequest, transferableBuffers } from './snapshot.js';
+import { TypfolioWorkerError, } from './types.js';
+export { TypfolioWorkerError, } from './types.js';
+export { collectBatch, compileBatch } from './batch.js';
+const maximumTimer = 2_147_483_647;
+function positiveInteger(value, fallback, name) {
+    const result = value ?? fallback;
+    if (!Number.isInteger(result) || result < 1)
+        throw new RangeError(`${name} must be a positive integer`);
+    return result;
+}
+function timeout(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < 1 || value > maximumTimer) {
+        throw new RangeError(`${name} must be an integer from 1 through ${maximumTimer}`);
+    }
+    return value;
+}
+function snapshotWasm(value) {
+    if (typeof value === 'string' || value instanceof WebAssembly.Module)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return value.slice(0);
+    if (value instanceof Uint8Array)
+        return new Uint8Array(value);
+    throw new TypeError('compiler.wasm must be a URL string, ArrayBuffer, Uint8Array, or WebAssembly.Module');
+}
+/** Bytes are copied; a URL becomes its `href`; a string is resolved here, because in a worker it would resolve against the worker script. */
+function snapshotFont(font, index) {
+    const at = `compiler.fonts[${index}]`;
+    if (font instanceof Uint8Array) {
+        if (!font.length)
+            throw new TypeError(`${at} must not be empty`);
+        return new Uint8Array(font);
+    }
+    if (font instanceof URL)
+        return font.href;
+    if (typeof font !== 'string' || !font.trim())
+        throw new TypeError(`${at} must be a Uint8Array, a URL, or a non-empty URL string`);
+    const base = globalThis.location?.href;
+    try {
+        return (base === undefined ? new URL(font) : new URL(font, base)).href;
+    }
+    catch (cause) {
+        throw new TypeError(`${at} cannot be resolved to a URL${base === undefined ? ' without a page URL; use an absolute URL' : ''}: ${JSON.stringify(font)}`, { cause });
+    }
+}
+function snapshotCompiler(value) {
+    if (!value || !Array.isArray(value.fonts) || !value.fonts.length) {
+        throw new TypeError('compiler.fonts must contain at least one Uint8Array, URL, or URL string');
+    }
+    return { wasm: snapshotWasm(value.wasm), fonts: value.fonts.map(snapshotFont) };
+}
+function workerError(message, cause) {
+    return new TypfolioWorkerError('WORKER', message, [], cause === undefined ? undefined : { cause });
+}
+function defaultWorkerFactory(name) {
+    return index => new Worker(new URL('./runtime.js', import.meta.url), { type: 'module', name: `${name}-${index + 1}` });
+}
+export function createWorkerClient(options) {
+    const compiler = snapshotCompiler(options.compiler);
+    const workerCount = positiveInteger(options.workerCount, 1, 'workerCount');
+    const queueLimit = positiveInteger(options.queueLimit, 32, 'queueLimit');
+    const defaultTimeout = timeout(options.timeoutMs, 'timeoutMs');
+    const createWorker = options.workerFactory ?? defaultWorkerFactory(options.workerName ?? 'typfolio-pdf');
+    const queue = [];
+    const slots = new Array(workerCount);
+    let nextId = 1;
+    let poolDisposed = false;
+    let clientDisposed = false;
+    let disposal;
+    function settle(job, result) {
+        if (job.settled)
+            return;
+        job.settled = true;
+        job.resume(result);
+    }
+    function terminateWorker(current) {
+        if (!current)
+            return;
+        if (slots[current.index] === current)
+            slots[current.index] = undefined;
+        current.worker.terminate();
+    }
+    function dispatchSoon() {
+        queueMicrotask(dispatch);
+    }
+    function failActive(error, current) {
+        if (slots[current.index] !== current)
+            return;
+        const job = current.active;
+        current.active = undefined;
+        terminateWorker(current);
+        const failed = job ?? queue.shift();
+        if (failed)
+            settle(failed, Effect.fail(error));
+        dispatchSoon();
+    }
+    function handleMessage(current, value) {
+        if (poolDisposed || slots[current.index] !== current)
+            return;
+        let message;
+        try {
+            message = decodeRuntimeMessage(value);
+        }
+        catch (cause) {
+            failActive(workerError('Typfolio worker returned an invalid message', cause), current);
+            return;
+        }
+        if (message.type === 'ready') {
+            if (current.ready) {
+                failActive(workerError('Typfolio worker initialized more than once'), current);
+                return;
+            }
+            current.ready = true;
+            dispatch();
+            return;
+        }
+        if (message.type === 'failure' && message.id === undefined) {
+            const error = new TypfolioWorkerError(message.error.code, message.error.message, message.error.diagnostics);
+            failActive(error, current);
+            return;
+        }
+        const job = current.active;
+        if (!job || message.id !== job.id)
+            return;
+        current.active = undefined;
+        if (message.type === 'result') {
+            settle(job, Effect.succeed(message.result));
+        }
+        else {
+            settle(job, Effect.fail(new TypfolioWorkerError(message.error.code, message.error.message, message.error.diagnostics)));
+        }
+        dispatch();
+    }
+    function createSlot(index) {
+        let worker;
+        try {
+            worker = createWorker(index);
+        }
+        catch (cause) {
+            const job = queue.shift();
+            if (job)
+                settle(job, Effect.fail(workerError('Could not create Typfolio worker', cause)));
+            dispatchSoon();
+            return false;
+        }
+        const current = { worker, index, ready: false };
+        slots[index] = current;
+        worker.addEventListener('message', event => handleMessage(current, event.data));
+        worker.addEventListener('error', event => {
+            failActive(workerError(event.message || 'Typfolio worker failed'), current);
+        });
+        worker.addEventListener('messageerror', () => {
+            failActive(workerError('Typfolio worker returned an unreadable message'), current);
+        });
+        const message = { protocol: protocolVersion, type: 'initialize', compiler };
+        try {
+            worker.postMessage(message);
+        }
+        catch (cause) {
+            failActive(workerError('Could not initialize Typfolio worker', cause), current);
+        }
+        return true;
+    }
+    function ensureCapacity() {
+        if (poolDisposed || !queue.length)
+            return;
+        const activeCount = slots.reduce((count, current) => count + (current?.active ? 1 : 0), 0);
+        const target = Math.min(workerCount, activeCount + queue.length);
+        let existing = slots.reduce((count, current) => count + (current ? 1 : 0), 0);
+        for (let index = 0; index < slots.length && existing < target; index += 1) {
+            if (!slots[index]) {
+                if (!createSlot(index))
+                    break;
+                existing += 1;
+            }
+        }
+    }
+    function dispatch() {
+        if (poolDisposed || !queue.length)
+            return;
+        ensureCapacity();
+        for (const current of slots) {
+            if (!current?.ready || current.active)
+                continue;
+            const job = queue.shift();
+            if (!job)
+                return;
+            current.active = job;
+            const message = { protocol: protocolVersion, type: 'compile', id: job.id, request: job.request };
+            try {
+                // A job is posted once: failed, cancelled, timed-out and crashed jobs are rejected, never re-posted, and a
+                // queued job leaves the queue as it is posted. So the snapshot's buffers can be transferred, not cloned.
+                current.worker.postMessage(message, transferableBuffers(job.request));
+            }
+            catch (cause) {
+                failActive(workerError('Could not send work to Typfolio worker', cause), current);
+            }
+        }
+    }
+    function interruptJob(job) {
+        if (job.settled)
+            return;
+        job.settled = true;
+        const current = slots.find(candidate => candidate?.active === job);
+        if (current) {
+            current.active = undefined;
+            terminateWorker(current);
+            dispatchSoon();
+            return;
+        }
+        const index = queue.indexOf(job);
+        if (index !== -1)
+            queue.splice(index, 1);
+    }
+    const compileJob = Effect.fnUntraced(function* (request) {
+        return yield* Effect.callback(resume => {
+            if (poolDisposed) {
+                resume(Effect.fail(new TypfolioWorkerError('DISPOSED', 'The worker client is disposed')));
+                return;
+            }
+            if (queue.length >= queueLimit) {
+                resume(Effect.fail(new TypfolioWorkerError('QUEUE_FULL', `The worker queue limit of ${queueLimit} was reached`)));
+                return;
+            }
+            const job = { id: nextId++, request, resume, settled: false };
+            queue.push(job);
+            dispatch();
+            return Effect.sync(() => interruptJob(job));
+        });
+    });
+    function waitForAbort(signal) {
+        return Effect.callback(resume => {
+            const abort = () => resume(Effect.fail(new TypfolioWorkerError('ABORTED', 'Compilation was cancelled', [], { cause: signal.reason })));
+            if (signal.aborted) {
+                abort();
+                return;
+            }
+            signal.addEventListener('abort', abort, { once: true });
+            return Effect.sync(() => signal.removeEventListener('abort', abort));
+        });
+    }
+    const disposePool = Effect.sync(() => {
+        if (poolDisposed)
+            return;
+        poolDisposed = true;
+        const error = new TypfolioWorkerError('DISPOSED', 'The worker client is disposed');
+        for (const current of slots) {
+            if (current?.active) {
+                const job = current.active;
+                current.active = undefined;
+                settle(job, Effect.fail(error));
+            }
+        }
+        for (const job of queue.splice(0))
+            settle(job, Effect.fail(error));
+        for (const current of slots)
+            terminateWorker(current);
+    });
+    const runtime = ManagedRuntime.make(Layer.effectDiscard(Effect.acquireRelease(Effect.void, () => disposePool)));
+    return {
+        workerCount,
+        compile(request, compileOptions = {}) {
+            if (clientDisposed)
+                return Promise.reject(new TypfolioWorkerError('DISPOSED', 'The worker client is disposed'));
+            if (compileOptions.signal?.aborted) {
+                return Promise.reject(new TypfolioWorkerError('ABORTED', 'Compilation was cancelled', [], { cause: compileOptions.signal.reason }));
+            }
+            let captured;
+            let duration;
+            try {
+                // A snapshot (from compileBatch) is already client-owned; copying it again would copy every asset twice.
+                captured = isSnapshot(request) ? request : snapshotRequest(request);
+                duration = timeout(compileOptions.timeoutMs, 'compile timeoutMs') ?? defaultTimeout;
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            let program = compileJob(captured);
+            if (duration !== undefined) {
+                program = Effect.timeoutOrElse(program, {
+                    duration,
+                    orElse: () => Effect.fail(new TypfolioWorkerError('TIMEOUT', `Compilation exceeded its ${duration} ms timeout`)),
+                });
+            }
+            if (compileOptions.signal) {
+                program = Effect.raceFirst(program, waitForAbort(compileOptions.signal));
+            }
+            return runtime.runPromise(program);
+        },
+        dispose() {
+            if (disposal)
+                return disposal;
+            clientDisposed = true;
+            return disposal = Effect.runPromise(disposePool).then(() => runtime.dispose());
+        },
+    };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,34 @@
+import type { Diagnostic, PdfRequest, PdfResult } from '@typfolio/core';
+import type { SerializedCompilerOptions, WorkerErrorCode } from './types.js';
+export declare const protocolVersion = 1;
+export type HostMessage = {
+    readonly protocol: 1;
+    readonly type: 'initialize';
+    readonly compiler: SerializedCompilerOptions;
+} | {
+    readonly protocol: 1;
+    readonly type: 'compile';
+    readonly id: number;
+    readonly request: PdfRequest<unknown>;
+};
+export interface SerializedError {
+    readonly code: WorkerErrorCode;
+    readonly message: string;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export type RuntimeMessage = {
+    readonly protocol: 1;
+    readonly type: 'ready';
+} | {
+    readonly protocol: 1;
+    readonly type: 'result';
+    readonly id: number;
+    readonly result: PdfResult;
+} | {
+    readonly protocol: 1;
+    readonly type: 'failure';
+    readonly id?: number;
+    readonly error: SerializedError;
+};
+export declare function decodeHostMessage(value: unknown): HostMessage;
+export declare function decodeRuntimeMessage(value: unknown): RuntimeMessage;

package/dist/protocol.js

@@ -0,0 +1,101 @@
+export const protocolVersion = 1;
+function record(value, at) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError(`${at} must be an object`);
+    }
+    return value;
+}
+function wasmSource(value) {
+    if (typeof value === 'string' || value instanceof ArrayBuffer || value instanceof Uint8Array || value instanceof WebAssembly.Module) {
+        return value;
+    }
+    throw new TypeError('compiler.wasm cannot cross the worker boundary');
+}
+function compilerOptions(value) {
+    const options = record(value, 'compiler');
+    if (!Array.isArray(options.fonts) || options.fonts.some(font => !(font instanceof Uint8Array || typeof font === 'string'))) {
+        throw new TypeError('compiler.fonts must contain Uint8Array or string values');
+    }
+    return {
+        wasm: wasmSource(options.wasm),
+        fonts: options.fonts.map((font) => typeof font === 'string' ? font : new Uint8Array(font)),
+    };
+}
+export function decodeHostMessage(value) {
+    const message = record(value, 'worker message');
+    if (message.protocol !== protocolVersion)
+        throw new TypeError('Unsupported Typfolio worker protocol');
+    if (message.type === 'initialize') {
+        return { protocol: protocolVersion, type: 'initialize', compiler: compilerOptions(message.compiler) };
+    }
+    if (message.type === 'compile' && Number.isSafeInteger(message.id)) {
+        const request = record(message.request, 'request');
+        return { protocol: protocolVersion, type: 'compile', id: Number(message.id), request };
+    }
+    throw new TypeError('Unknown Typfolio worker message');
+}
+function diagnostic(value) {
+    const item = record(value, 'diagnostic');
+    if (typeof item.severity !== 'string' || typeof item.message !== 'string')
+        throw new TypeError('Invalid worker diagnostic');
+    return {
+        severity: item.severity,
+        message: item.message,
+        path: typeof item.path === 'string' ? item.path : undefined,
+        range: typeof item.range === 'string' ? item.range : undefined,
+        package: typeof item.package === 'string' ? item.package : undefined,
+    };
+}
+function serializedError(value) {
+    const error = record(value, 'worker error');
+    if (typeof error.code !== 'string' || typeof error.message !== 'string' || !Array.isArray(error.diagnostics)) {
+        throw new TypeError('Invalid worker error');
+    }
+    const codes = [
+        'INITIALIZATION', 'INVALID_REQUEST', 'UNSUPPORTED_OPTION', 'BUSY', 'DISPOSED',
+        'ABORTED', 'COMPILATION', 'ENGINE', 'WORKER', 'TIMEOUT', 'QUEUE_FULL',
+    ];
+    const code = codes.find(candidate => candidate === error.code);
+    if (!code)
+        throw new TypeError('Invalid worker error code');
+    return {
+        code,
+        message: error.message,
+        diagnostics: error.diagnostics.map(diagnostic),
+    };
+}
+function result(value) {
+    const item = record(value, 'worker result');
+    const bytes = item.bytes instanceof Uint8Array
+        ? item.bytes
+        : item.bytes instanceof ArrayBuffer ? new Uint8Array(item.bytes) : undefined;
+    if (!bytes || !Array.isArray(item.diagnostics))
+        throw new TypeError('Invalid worker PDF result');
+    const metadata = record(item.metadata, 'worker result metadata');
+    if (metadata.title !== undefined && typeof metadata.title !== 'string')
+        throw new TypeError('Invalid worker PDF title');
+    return {
+        bytes,
+        diagnostics: item.diagnostics.map(diagnostic),
+        metadata: { title: metadata.title },
+    };
+}
+export function decodeRuntimeMessage(value) {
+    const message = record(value, 'runtime message');
+    if (message.protocol !== protocolVersion)
+        throw new TypeError('Unsupported Typfolio worker protocol');
+    if (message.type === 'ready')
+        return { protocol: protocolVersion, type: 'ready' };
+    if (message.type === 'result' && Number.isSafeInteger(message.id)) {
+        return { protocol: protocolVersion, type: 'result', id: Number(message.id), result: result(message.result) };
+    }
+    if (message.type === 'failure' && (message.id === undefined || Number.isSafeInteger(message.id))) {
+        return {
+            protocol: protocolVersion,
+            type: 'failure',
+            id: message.id === undefined ? undefined : Number(message.id),
+            error: serializedError(message.error),
+        };
+    }
+    throw new TypeError('Unknown Typfolio runtime message');
+}

package/dist/runtime.d.ts

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

package/dist/runtime.js

@@ -0,0 +1,2 @@
+import { installWorkerRuntime } from './worker-runtime.js';
+installWorkerRuntime(self);

package/dist/snapshot.d.ts

@@ -0,0 +1,10 @@
+import type { PdfRequest } from '@typfolio/core';
+export declare function isSnapshot(request: unknown): boolean;
+export declare function snapshotRequest(request: PdfRequest<unknown>): PdfRequest<unknown>;
+/**
+ * The buffers of a snapshot's assets that `postMessage` can transfer, each once. Buffers that cannot be
+ * transferred (a `SharedArrayBuffer`, which structured clone shares instead of copying, or one that is already
+ * detached) are left out and travel by the ordinary clone. Only call this with a snapshot: transferring detaches
+ * the buffers, which would break a caller's request.
+ */
+export declare function transferableBuffers(snapshot: PdfRequest<unknown>): ArrayBuffer[];

package/dist/snapshot.js

@@ -0,0 +1,62 @@
+import { TypfolioWorkerError } from './types.js';
+function inspectCloneable(value, ancestors, at) {
+    if (typeof value === 'function' || typeof value === 'symbol') {
+        throw new TypeError(`${at} cannot cross the worker boundary`);
+    }
+    if (typeof value !== 'object' || value === null || value instanceof Uint8Array || value instanceof ArrayBuffer)
+        return;
+    if (ancestors.has(value))
+        throw new TypeError(`${at} contains a cycle`);
+    if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+        throw new TypeError(`${at} must contain only plain objects, arrays, and Uint8Array assets`);
+    }
+    if (Object.getOwnPropertySymbols(value).length)
+        throw new TypeError(`${at} contains symbol keys`);
+    ancestors.add(value);
+    try {
+        for (const key of Object.keys(value)) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !('value' in descriptor))
+                throw new TypeError(`${at}.${key} contains an accessor`);
+            inspectCloneable(descriptor.value, ancestors, `${at}.${key}`);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+// Every request returned by snapshotRequest. The client owns these (nothing else holds their buffers), so it
+// neither snapshots them again nor hesitates to transfer them.
+const snapshots = new WeakSet();
+export function isSnapshot(request) {
+    return typeof request === 'object' && request !== null && snapshots.has(request);
+}
+export function snapshotRequest(request) {
+    try {
+        inspectCloneable(request, new Set(), 'request');
+        const snapshot = structuredClone(request);
+        snapshots.add(snapshot);
+        return snapshot;
+    }
+    catch (cause) {
+        throw new TypfolioWorkerError('INVALID_REQUEST', 'The PDF request cannot cross the worker boundary', [], { cause });
+    }
+}
+/**
+ * The buffers of a snapshot's assets that `postMessage` can transfer, each once. Buffers that cannot be
+ * transferred (a `SharedArrayBuffer`, which structured clone shares instead of copying, or one that is already
+ * detached) are left out and travel by the ordinary clone. Only call this with a snapshot: transferring detaches
+ * the buffers, which would break a caller's request.
+ */
+export function transferableBuffers(snapshot) {
+    const buffers = new Set();
+    for (const bytes of Object.values(snapshot.assets ?? {})) {
+        if (!ArrayBuffer.isView(bytes))
+            continue; // Not an asset; the worker's validation rejects it.
+        const buffer = bytes.buffer;
+        if (Object.prototype.toString.call(buffer) === '[object ArrayBuffer]' && !buffer.detached) {
+            buffers.add(buffer);
+        }
+    }
+    return [...buffers];
+}

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+import type { Diagnostic, ErrorCode, PdfClient, PdfRequest, PdfResult } from '@typfolio/core';
+/** WASM sources that the structured-clone worker protocol can carry reliably. */
+export type WorkerWasmSource = string | ArrayBuffer | Uint8Array | WebAssembly.Module;
+/**
+ * Font bytes, or a URL that each worker fetches itself, so the bytes never cross the worker boundary.
+ * A string is resolved against the page URL on the client thread before it is sent.
+ */
+export type WorkerFontSource = Uint8Array | string | URL;
+export interface WorkerCompilerOptions {
+    readonly wasm: WorkerWasmSource;
+    readonly fonts: readonly WorkerFontSource[];
+}
+/** What crosses the worker boundary: a `URL` has become its absolute `href`. */
+export interface SerializedCompilerOptions {
+    readonly wasm: WorkerWasmSource;
+    readonly fonts: readonly (Uint8Array | string)[];
+}
+export interface WorkerCompileOptions {
+    readonly signal?: AbortSignal;
+    /** Includes time spent waiting in the queue. */
+    readonly timeoutMs?: number;
+}
+export interface PdfWorkerClient extends PdfClient {
+    readonly workerCount: number;
+    compile(request: PdfRequest<unknown>, options?: WorkerCompileOptions): Promise<PdfResult>;
+    /** Rejects queued/active jobs and terminates all owned workers. Idempotent. */
+    dispose(): Promise<void>;
+}
+export interface CreateWorkerClientOptions {
+    readonly compiler: WorkerCompilerOptions;
+    /** Maximum parallel compilations. Workers are created lazily. Defaults to one. */
+    readonly workerCount?: number;
+    /** Maximum number of waiting jobs, excluding the active compilation. */
+    readonly queueLimit?: number;
+    /** Default per-job timeout, including queue time. Omit for no timeout. */
+    readonly timeoutMs?: number;
+    /** Used by the built-in module-worker factory. */
+    readonly workerName?: string;
+    /** Test/custom-host escape hatch. The client owns and terminates each worker. */
+    readonly workerFactory?: (index: number) => Worker;
+}
+export interface PdfBatchJob<Id> {
+    readonly id: Id;
+    readonly request: PdfRequest<unknown>;
+    readonly timeoutMs?: number;
+}
+export type PdfBatchOutcome<Id> = {
+    readonly id: Id;
+    readonly index: number;
+    readonly status: 'success';
+    readonly result: PdfResult;
+} | {
+    readonly id: Id;
+    readonly index: number;
+    readonly status: 'error';
+    readonly error: TypfolioWorkerError;
+} | {
+    readonly id: Id;
+    readonly index: number;
+    readonly status: 'cancelled';
+};
+export interface PdfBatchProgress<Id> {
+    readonly total: number;
+    readonly completed: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly cancelled: number;
+    readonly latestJobId?: Id;
+}
+export interface PdfBatchOptions<Id> {
+    readonly signal?: AbortSignal;
+    readonly onItemSettled?: (outcome: PdfBatchOutcome<Id>, progress: PdfBatchProgress<Id>) => void;
+    readonly onProgress?: (progress: PdfBatchProgress<Id>) => void;
+}
+export type WorkerErrorCode = ErrorCode | 'WORKER' | 'TIMEOUT' | 'QUEUE_FULL';
+export declare class TypfolioWorkerError extends Error {
+    readonly code: WorkerErrorCode;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly name = "TypfolioWorkerError";
+    constructor(code: WorkerErrorCode, message: string, diagnostics?: readonly Diagnostic[], options?: ErrorOptions);
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+export class TypfolioWorkerError extends Error {
+    code;
+    diagnostics;
+    name = 'TypfolioWorkerError';
+    constructor(code, message, diagnostics = [], options) {
+        super(message, options);
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}

package/dist/worker-runtime.d.ts

@@ -0,0 +1,6 @@
+import { type RuntimeMessage } from './protocol.js';
+export interface WorkerRuntimeScope {
+    addEventListener(type: 'message', listener: (event: MessageEvent<unknown>) => void): void;
+    postMessage(message: RuntimeMessage, transfer?: readonly Transferable[]): void;
+}
+export declare function installWorkerRuntime(scope: WorkerRuntimeScope): void;

package/dist/worker-runtime.js

@@ -0,0 +1,65 @@
+import { createCompiler, TypstPdfError } from '@typfolio/core';
+import { decodeHostMessage, protocolVersion } from './protocol.js';
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+function serializeError(error) {
+    if (error instanceof TypstPdfError) {
+        return { code: error.code, message: error.message, diagnostics: error.diagnostics };
+    }
+    return { code: 'WORKER', message: errorMessage(error), diagnostics: [] };
+}
+function transferable(bytes) {
+    return bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength ? bytes : bytes.slice();
+}
+export function installWorkerRuntime(scope) {
+    let compiler;
+    let initializing;
+    scope.addEventListener('message', event => {
+        let requestId;
+        try {
+            const message = decodeHostMessage(event.data);
+            if (message.type === 'initialize') {
+                if (initializing || compiler)
+                    throw new Error('Typfolio worker is already initialized');
+                // The request is owned by this worker (a transferred snapshot), so core need not copy its assets again.
+                initializing = createCompiler({ ...message.compiler, copyAssets: false }).then(value => {
+                    compiler = value;
+                    scope.postMessage({ protocol: protocolVersion, type: 'ready' });
+                }).catch(error => {
+                    scope.postMessage({ protocol: protocolVersion, type: 'failure', error: serializeError(error) });
+                });
+                return;
+            }
+            requestId = message.id;
+            if (!compiler)
+                throw new Error('Typfolio worker is not ready');
+            void compiler.compile(message.request).then(result => {
+                const bytes = transferable(result.bytes);
+                scope.postMessage({
+                    protocol: protocolVersion,
+                    type: 'result',
+                    id: message.id,
+                    result: { ...result, bytes },
+                }, [bytes.buffer]);
+            }).catch(error => {
+                scope.postMessage({
+                    protocol: protocolVersion,
+                    type: 'failure',
+                    id: message.id,
+                    error: serializeError(error),
+                });
+            });
+        }
+        catch (error) {
+            scope.postMessage({
+                protocol: protocolVersion,
+                type: 'failure',
+                id: requestId,
+                error: serializeError(error),
+            });
+        }
+    });
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@typfolio/workers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Framework-independent Web Worker execution for Typfolio PDF compilation",
+  "type": "module",
+  "license": "Apache-2.0",
+  "keywords": ["typst", "pdf", "wasm", "webassembly", "web-worker", "browser", "concurrency"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HelioCampus/typfolio.git",
+    "directory": "packages/workers"
+  },
+  "homepage": "https://github.com/HelioCampus/typfolio#readme",
+  "bugs": { "url": "https://github.com/HelioCampus/typfolio/issues" },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": "./dist/runtime.js"
+  },
+  "dependencies": {
+    "@typfolio/core": "^0.1.0",
+    "effect": "4.0.0-rc.118"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": { "node": ">=22" },
+  "sideEffects": [
+    "./dist/runtime.js"
+  ]
+}