@nomercy-entertainment/nomercy-subtitle-octopus 0.1.0

package/COPYRIGHT

@@ -0,0 +1,25 @@
+The WASM binaries in the public/ directory of this package are derived from
+libass-wasm (SubtitleOctopus), originally authored by Dador and maintained by
+the Jellyfin project contributors.
+
+Source: https://github.com/jellyfin/jellyfin-web (libass-wasm integration)
+        https://github.com/libass/libass
+
+License: GNU Lesser General Public License v2.1 (LGPL-2.1)
+The full text of LGPL-2.1 is available at:
+https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
+
+The TypeScript wrapper code in src/ is original work by NoMercy Entertainment
+and is licensed under MIT.
+
+---
+
+libass is Copyright (C) 2006-2022 libass contributors.
+SubtitleOctopus WASM port is Copyright (C) Dador and contributors.
+Jellyfin libass-wasm integration is Copyright (C) Jellyfin contributors.
+
+This package distributes the compiled WASM output only. The wrapper does not
+incorporate any source code from the upstream projects.
+
+TODO(NME-octopus): Replace vendored WASM binaries with an in-house Emscripten
+build that includes NoMercy-specific patches directly in the C layer.

package/README.md

@@ -0,0 +1,75 @@
+# @nomercy-entertainment/nomercy-subtitle-octopus
+
+NoMercy-owned TypeScript wrapper around the libass-wasm (SubtitleOctopus) WASM renderer.
+
+This package is **not** a fork of upstream — it's a thin consumer-side wrapper that adds the patches NoMercy needs without modifying the WASM worker. The actual fork of [libass/JavascriptSubtitlesOctopus](https://github.com/libass/JavascriptSubtitlesOctopus) lives at [`@nomercy-entertainment/libass-wasm`](../nomercy-libass-wasm/) — that package owns the C++ source, Emscripten build pipeline, and the binaries.
+
+## Patches owned here (main-thread, TypeScript)
+
+- **Bearer token auth** — pre-fetch subtitle + font files on the main thread with `Authorization: Bearer <token>`, hand the worker blob URLs. Worker stays unmodified, never makes auth-required calls. Custom request schemes (`nmsync:`, `cast:`, `data:`, `blob:`, `file:`, etc.) bypass the same-origin guard so the token never leaks onto requests that can't carry it.
+- **Cross-origin worker instantiation** — Blob URL + `importScripts()` shim so workers load from a different origin (CDN deployments).
+- **Canvas geometry sync** — `ResizeObserver` against a configurable `geometrySource` element; copies six CSS properties to `canvasParent` so the libass canvas tracks the player's overlay through fullscreen / theater / float transitions.
+- **Lifecycle race guards** — `currentLoadedUrl` + race-token pattern, orphan canvas sweep, idempotent dispose.
+- **URL resolution** — `basePath` prepend with proper RFC-3986 absolute-URL detection (any scheme, plus protocol-relative `//host/path`).
+
+## Binaries
+
+`public/subtitles-octopus-worker.{js,wasm}` and `public/default.ttf` are vendored from upstream `libass-wasm@4.1.0` pending a first NoMercy build out of the sister fork (`@nomercy-entertainment/libass-wasm`). License chain reproduced in `COPYRIGHT`.
+
+## Worker files — copy to public
+
+The libass WASM worker files ship inside this package's `dist/` directory. Your build tool must copy them into the public/static directory so the browser can load them:
+
+```ts
+// vite.config.ts
+import { viteStaticCopy } from 'vite-plugin-static-copy';
+
+export default {
+  plugins: [
+    viteStaticCopy({
+      targets: [
+        {
+          src: 'node_modules/@nomercy-entertainment/nomercy-subtitle-octopus/dist/subtitles-octopus-worker*.{js,wasm,data}',
+          dest: 'static',
+        },
+      ],
+    }),
+  ],
+};
+```
+
+Then pass the copied paths when registering the plugin:
+
+```ts
+player.addPlugin(OctopusPlugin, {
+  workerUrl: '/static/subtitles-octopus-worker.js',
+  legacyWorkerUrl: '/static/subtitles-octopus-worker-legacy.js',
+});
+```
+
+## Usage
+
+```ts
+import { NMSubtitleOctopus } from '@nomercy-entertainment/nomercy-subtitle-octopus';
+
+// Pre-fetch subtitle bytes and font binaries with whatever auth pipeline you use.
+const trackContent = await fetchAuthedText('/episode-1.ass');
+const availableFonts = await fetchAuthedFonts('/fonts/');
+
+const octopus = new NMSubtitleOctopus({
+	video: videoElement,
+	trackContent,
+	availableFonts,
+	geometrySource: playerContainer,
+});
+
+octopus.on('rendererReady', ({ url }) => console.log('renderer ready', url));
+```
+
+The renderer never performs authenticated network I/O — your consumer (or the
+NoMercy player kit) pre-fetches every byte the worker needs and passes it as
+`trackContent` plus a `name → blob:URL` font map.
+
+## License
+
+MIT — TypeScript wrapper code. The vendored WASM artefact carries the upstream license chain (LGPL-2.1 / FTL / GPL-2.0 / MIT / ISC / NTP / Zlib / BSL-1.0) reproduced in `COPYRIGHT`.

package/dist/canvas-geometry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Patch 3 — ResizeObserver-driven canvas geometry sync.
+ *
+ * v1 behaviour: on every window resize the wrapper copied six CSS properties
+ * from the player container onto the libass canvas parent so the subtitle
+ * overlay stayed pixel-locked to the video even when the layout shifted.
+ */
+export declare class CanvasGeometry {
+    private readonly source;
+    private readonly target;
+    private observer;
+    constructor(source: HTMLElement, target: HTMLElement);
+    attach(): void;
+    detach(): void;
+    private sync;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { CanvasGeometry } from './canvas-geometry';
+export { isSupportedSubtitle, Lifecycle, RaceToken, sweepOrphanCanvases } from './lifecycle';
+export { NMSubtitleOctopus } from './octopus';
+export type { OctopusEvents, OctopusOptions, RenderMode } from './types';
+export { resolveUrl } from './url-resolution';
+export { createWorker, EventEmitter, WorkerBridge } from './worker-bridge';

package/dist/lifecycle.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Patch 4 — Worker reuse prevention and instance lifecycle race guards.
+ *
+ * v1 behaviour: rapid subtitle switches left stale worker instances alive
+ * and stale canvas elements in the DOM. The wrapper tracked the loaded URL
+ * and aborted in-flight loads if the URL changed during async operations.
+ * Orphan `.libassjs-canvas-parent` elements were swept before each new mount.
+ */
+/** True when the URL points to a supported subtitle format. */
+export declare function isSupportedSubtitle(url: string): boolean;
+/**
+ * Remove stale `.libassjs-canvas-parent` elements from `container`.
+ * Prevents ghost overlays after hot-reload or rapid plugin re-init.
+ */
+export declare function sweepOrphanCanvases(container: HTMLElement): void;
+/**
+ * Lightweight race token. Callers obtain a new token before each async
+ * operation and check `.cancelled` after every await to abort stale work.
+ */
+export declare class RaceToken {
+    cancelled: boolean;
+}
+/**
+ * Thin lifecycle wrapper around a disposable resource.
+ * Tracks cleanup callbacks added during setup and runs them in reverse on destroy.
+ */
+export declare class Lifecycle {
+    private cleanups;
+    addCleanup(fn: () => void): void;
+    destroy(): void;
+}