niers-media 1.0.0

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "niers-media",
+	"version": "1.0.0",
+	"private": false,
+	"type": "module",
+	"description": "Canonical Inazuma Eleven media catalogue, source URLs, navigation and player contracts.",
+	"publishConfig": {
+		"access": "public"
+	},
+	"exports": {
+		".": "./src/index.ts",
+		"./catalog": "./src/catalog.ts",
+		"./navigation": "./src/navigation.ts",
+		"./player": "./src/player.ts",
+		"./url": "./src/url.ts",
+		"./work": "./src/work.ts",
+		"./manga": "./src/manga.ts",
+		"./runtime": "./src/runtime.ts"
+	},
+	"scripts": {
+		"typecheck": "bunx tsc --noEmit",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@types/bun": "1.3.14",
+		"typescript": "5.9.3"
+	}
+}

package/src/canon.ts

@@ -0,0 +1,45 @@
+import type { GameFamily, GamePlatform, WorkRef } from "./work";
+import { runtimeLinksForPlatforms } from "./runtime";
+
+export interface GameRelease {
+	id: string;
+	work: WorkRef;
+	family: GameFamily;
+	platform: GamePlatform;
+	title: string;
+	acquisition: "official_purchase" | "owned_original" | "community_build";
+	sourceUrl?: string | null;
+	region?: string | null;
+	}
+
+/** Measured catalogue anchors; missing releases remain explicit instead of invented. */
+export const CANONICAL_GAME_FAMILIES: readonly WorkRef[] = [
+	{ id: "inazuma_eleven_ds", kind: "game", title: "Inazuma Eleven", series: "inazuma_eleven", platforms: ["ds"], runtimeLinks: runtimeLinksForPlatforms(["ds"]) },
+	{ id: "inazuma_eleven_2_ds", kind: "game", title: "Inazuma Eleven 2", series: "inazuma_eleven_2", platforms: ["ds"], runtimeLinks: runtimeLinksForPlatforms(["ds"]) },
+	{ id: "inazuma_eleven_3_ds", kind: "game", title: "Inazuma Eleven 3", series: "inazuma_eleven_3", platforms: ["ds"], runtimeLinks: runtimeLinksForPlatforms(["ds"]) },
+	{ id: "inazuma_eleven_go_3ds", kind: "game", title: "Inazuma Eleven GO", series: "inazuma_eleven_go", platforms: ["3ds"], runtimeLinks: runtimeLinksForPlatforms(["3ds"]) },
+	{ id: "inazuma_eleven_go_chrono_stones_3ds", kind: "game", title: "Inazuma Eleven GO Chrono Stones", series: "inazuma_eleven_go_chrono_stones", platforms: ["3ds"], runtimeLinks: runtimeLinksForPlatforms(["3ds"]) },
+	{ id: "inazuma_eleven_go_galaxy_3ds", kind: "game", title: "Inazuma Eleven GO Galaxy", series: "inazuma_eleven_go_galaxy", platforms: ["3ds"], runtimeLinks: runtimeLinksForPlatforms(["3ds"]) },
+	{ id: "inazuma_eleven_strikers_wii", kind: "game", title: "Inazuma Eleven Strikers", series: "inazuma_eleven_strikers", platforms: ["wii"], runtimeLinks: runtimeLinksForPlatforms(["wii"]) },
+	{ id: "inazuma_eleven_strikers_2012_wii", kind: "game", title: "Inazuma Eleven Strikers 2012 Extreme", series: "inazuma_eleven_strikers_2012", platforms: ["wii"], runtimeLinks: runtimeLinksForPlatforms(["wii"]) },
+	{ id: "inazuma_eleven_strikers_2013_wii", kind: "game", title: "Inazuma Eleven GO Strikers 2013", series: "inazuma_eleven_strikers_2013", platforms: ["wii"], runtimeLinks: runtimeLinksForPlatforms(["wii"]) },
+	{ id: "inazuma_eleven_victory_road", kind: "game", title: "Inazuma Eleven: Victory Road", series: "inazuma_eleven_victory_road", platforms: ["switch", "switch_2", "ps4", "ps5", "xbox", "pc"], runtimeLinks: runtimeLinksForPlatforms(["switch", "switch_2", "ps4", "ps5", "xbox", "pc"]) },
+	{ id: "inazuma_eleven_cross", kind: "game", title: "Inazuma Eleven: Cross", series: "inazuma_eleven_cross", platforms: ["ios", "android", "mobile"], runtimeLinks: runtimeLinksForPlatforms(["ios", "android", "mobile"]) },
+];
+
+/** Release/edition anchors. Patch numbers belong here only after a measured source is recorded. */
+export const CANONICAL_GAME_RELEASES: readonly GameRelease[] = CANONICAL_GAME_FAMILIES.flatMap((work) =>
+	(work.platforms ?? []).map((platform) => ({
+		id: `${work.id}:${platform}`,
+		work,
+		family: work.series ?? "other",
+		platform,
+		title: work.title,
+		acquisition: "official_purchase" as const,
+		region: null,
+	})),
+);
+
+export function gamesForPlatform(platform: GamePlatform): WorkRef[] {
+	return CANONICAL_GAME_FAMILIES.filter((work) => work.platforms?.includes(platform));
+}

package/src/catalog.ts

@@ -0,0 +1,36 @@
+import type { MediaEntry } from "./work";
+import { sortMediaEntries } from "./navigation";
+
+export interface MediaQuery {
+	text?: string;
+	kind?: MediaEntry["kind"];
+	series?: string;
+	season?: number;
+	language?: string;
+}
+
+export function mergeMediaEntries(...catalogues: readonly (readonly MediaEntry[])[]): MediaEntry[] {
+	const merged = new Map<string, MediaEntry>();
+	for (const catalogue of catalogues) {
+		for (const entry of catalogue) {
+			const previous = merged.get(entry.id);
+			merged.set(entry.id, previous ? { ...previous, sources: [...previous.sources, ...entry.sources] } : entry);
+		}
+	}
+	return sortMediaEntries([...merged.values()].map((entry) => ({
+		...entry,
+		sources: [...new Map(entry.sources.map((source) => [`${source.platform}:${source.id}`, source])).values()],
+	})));
+}
+
+export function queryMedia(entries: readonly MediaEntry[], query: MediaQuery = {}): MediaEntry[] {
+	const text = query.text?.trim().toLocaleLowerCase();
+	return sortMediaEntries(entries.filter((entry) => {
+		if (query.kind && entry.kind !== query.kind) return false;
+		if (query.series && entry.work.series !== query.series) return false;
+		if (query.season !== undefined && entry.season !== query.season) return false;
+		if (query.language && !entry.sources.some((source) => source.language === query.language)) return false;
+		if (text && !`${entry.title} ${entry.titleOriginal ?? ""} ${entry.work.title}`.toLocaleLowerCase().includes(text)) return false;
+		return true;
+	}));
+}

package/src/inazuma-tv.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+import { parseOfficialCategories, parseOfficialEpisodes, parseYoutubeAtom } from "./inazuma-tv";
+
+describe("Inazuma TV pure adapters", () => {
+	test("reads official JSON-LD categories and episode numbers from URLs", () => {
+		const html = `<script type="application/ld+json">${JSON.stringify({
+			"@type": "ItemList", name: "Categories", itemListElement: [{ position: 1, name: "Saison 1", url: "https://example.test/tv/saison1" }],
+		})}</script><script type="application/ld+json">${JSON.stringify({
+			"@type": "ItemList", name: "Episodes", itemListElement: [{ position: 1, name: "Épisode 12 - Le match", url: "https://example.test/ep-12" }],
+		})}</script>`;
+		expect(parseOfficialCategories(html)[0]?.slug).toBe("saison1");
+		expect(parseOfficialEpisodes(html)[0]?.number).toBe(12);
+	});
+
+	test("reads the finite Atom feed without scraping a rendered YouTube page", () => {
+		const xml = `<feed><title>Inazuma TV</title><entry><yt:videoId>abc12345678</yt:videoId><title>Episode 1</title><published>2026-01-01</published></entry></feed>`;
+		expect(parseYoutubeAtom(xml)[0]).toMatchObject({ videoId: "abc12345678", channel: "Inazuma TV" });
+	});
+});

package/src/inazuma-tv.ts

@@ -0,0 +1,121 @@
+import type { MediaEntry, MediaSource, WorkRef } from "./work";
+import { mediaId, workId } from "./work";
+import { runtimeForMediaKind } from "./runtime";
+
+export interface OfficialCategory {
+	position: number;
+	name: string;
+	url: string;
+	slug: string;
+}
+
+export interface OfficialEpisode {
+	number: number;
+	title: string;
+	url: string;
+}
+
+export interface AtomVideo {
+	videoId: string;
+	title: string;
+	url: string;
+	published: string | null;
+	channel: string | null;
+}
+
+export function slugFromUrl(url: string): string {
+	const path = url.split(/[?#]/, 1)[0]!.replace(/\/+$/, "");
+	return path.slice(path.lastIndexOf("/") + 1);
+}
+
+export function parseOfficialCategories(html: string): OfficialCategory[] {
+	return parseItemList(html, (name) => /categor/i.test(name))
+		.map((item) => ({ ...item, slug: slugFromUrl(item.url) }))
+		.filter((item) => item.slug.length > 0);
+}
+
+export function parseOfficialEpisodes(html: string): OfficialEpisode[] {
+	return parseItemList(html, (name) => /episode/i.test(name))
+		.map((item) => ({
+			number: Number.parseInt(/\/ep-(\d+)/i.exec(item.url)?.[1] ?? String(item.position), 10),
+			title: item.name.replace(/^\s*(?:episode|épisode)\s*\d+\s*[-–—:]\s*/i, "").trim(),
+			url: item.url,
+		}))
+		.filter((episode) => Number.isFinite(episode.number));
+}
+
+export function parseYoutubeAtom(xml: string): AtomVideo[] {
+	const beforeEntries = xml.split("<entry>", 1)[0] ?? "";
+	const channel = textTag(beforeEntries, "title");
+	const entries: AtomVideo[] = [];
+	for (const match of xml.matchAll(/<entry>([\s\S]*?)<\/entry>/g)) {
+		const body = match[1]!;
+		const videoId = textTag(body, "yt:videoId");
+		const title = textTag(body, "title");
+		if (!videoId || !title) continue;
+		entries.push({ videoId, title, url: `https://www.youtube.com/watch?v=${videoId}`, published: textTag(body, "published"), channel });
+	}
+	return entries;
+}
+
+export function officialEpisodeEntry(
+	category: OfficialCategory,
+	episode: OfficialEpisode,
+	work: WorkRef = { id: workId("inazuma_eleven"), kind: "anime", title: "Inazuma Eleven", series: "inazuma_eleven" },
+): MediaEntry {
+	return {
+		id: mediaId("episode", `${category.slug}_${episode.number}`),
+		kind: "episode",
+		work,
+		title: episode.title,
+		season: category.position,
+		episode: episode.number,
+		runtime: runtimeForMediaKind("episode"),
+		sources: [{ platform: "official_page", id: episode.url, url: episode.url, official: true, verified: true }],
+	};
+}
+
+function parseItemList(html: string, accepts: (name: string) => boolean): { position: number; name: string; url: string }[] {
+	for (const object of jsonLdObjects(html)) {
+		if (object["@type"] !== "ItemList" || !accepts(typeof object.name === "string" ? object.name : "")) continue;
+		if (!Array.isArray(object.itemListElement)) continue;
+		return object.itemListElement.map((raw, index) => {
+			const item = raw as Record<string, unknown>;
+			return {
+				position: typeof item.position === "number" ? item.position : index + 1,
+				name: typeof item.name === "string" ? item.name.trim() : "",
+				url: typeof item.url === "string" ? item.url.trim() : "",
+			};
+		}).filter((item) => item.name.length > 0 && item.url.length > 0);
+	}
+	return [];
+}
+
+function jsonLdObjects(html: string): Record<string, unknown>[] {
+	const result: Record<string, unknown>[] = [];
+	for (const match of html.matchAll(/<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)) {
+		try {
+			const value: unknown = JSON.parse(match[1]!);
+			for (const root of Array.isArray(value) ? value : [value]) {
+				if (!root || typeof root !== "object") continue;
+				const object = root as Record<string, unknown>;
+				const graph = object["@graph"];
+				if (Array.isArray(graph)) result.push(...graph.filter((item): item is Record<string, unknown> => Boolean(item && typeof item === "object")));
+				else result.push(object);
+			}
+		} catch {
+			// One malformed JSON-LD block must not hide the other structured blocks.
+		}
+	}
+	return result;
+}
+
+function textTag(xml: string, name: string): string | null {
+	const match = new RegExp(`<${name}(?:\\s[^>]*)?>([\\s\\S]*?)</${name}>`).exec(xml);
+	return match ? decodeXml(match[1]!) : null;
+}
+
+function decodeXml(value: string): string {
+	return value.replace(/&lt;/g, "<").replace(/&gt;/g, ">")
+		.replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&#39;/g, "'").replace(/&amp;/g, "&");
+}

package/src/index.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { mergeMediaEntries, queryMedia } from "./catalog";
+import { neighboringEntries } from "./navigation";
+import { sourcePlayerUrl } from "./player";
+import { mediaEntryPath } from "./url";
+import type { MediaEntry } from "./work";
+
+const episode: MediaEntry = {
+	id: "episode:inazuma_eleven_1_1",
+	kind: "episode",
+	work: { id: "inazuma_eleven", kind: "anime", title: "Inazuma Eleven", series: "inazuma_eleven" },
+	title: "Episode 1",
+	season: 1,
+	episode: 1,
+	sources: [{ platform: "youtube", id: "abc12345678", url: "https://youtu.be/abc12345678", official: true }],
+};
+
+describe("canonical media catalogue", () => {
+	test("merges sources without duplicating the entry", () => {
+		const merged = mergeMediaEntries([episode], [{ ...episode, sources: [{ ...episode.sources[0]!, id: "other1234567" }] }]);
+		expect(merged).toHaveLength(1);
+		expect(merged[0]!.sources).toHaveLength(2);
+	});
+
+	test("queries canonically and builds stable routes", () => {
+		expect(queryMedia([episode], { series: "inazuma_eleven" })[0]!.id).toBe(episode.id);
+		expect(mediaEntryPath(episode)).toBe("/episodes/episode%3Ainazuma_eleven_1_1");
+	});
+
+	test("keeps player URL policy in one owner", () => {
+		expect(sourcePlayerUrl(episode.sources[0]!, 12)).toContain("start=12");
+		expect(neighboringEntries([episode], episode.id).next).toBeNull();
+	});
+});

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./catalog";
+export * from "./canon";
+export * from "./inazuma-tv";
+export * from "./navigation";
+export * from "./player";
+export * from "./url";
+export * from "./work";
+export * from "./manga";
+export * from "./runtime";

package/src/manga.ts

@@ -0,0 +1,27 @@
+import type { MediaEntry, WorkRef } from "./work";
+import { runtimeForMediaKind } from "./runtime";
+
+export interface MangaVolume {
+	work: WorkRef;
+	volume: number;
+	title: string;
+	url?: string | null;
+	publisher?: string | null;
+	official?: boolean;
+}
+
+/** Adapts a manga volume to the same catalogue consumed by films and episodes. */
+export function mangaVolumeEntry(volume: MangaVolume): MediaEntry {
+	return {
+		id: `${volume.work.id}:manga:${volume.volume}`,
+		kind: "manga_volume",
+		work: volume.work,
+		title: volume.title,
+		season: volume.volume,
+		volume: volume.volume,
+		runtime: runtimeForMediaKind("manga_volume"),
+		sources: volume.url
+			? [{ id: `${volume.work.id}:manga:${volume.volume}:source`, platform: "manga_publisher", url: volume.url, official: volume.official ?? false }]
+			: [],
+	};
+}

package/src/navigation.ts

@@ -0,0 +1,41 @@
+import type { MediaEntry } from "./work";
+
+export function nextUnwatchedEpisode(available: readonly number[], watched: ReadonlySet<number>): number | null {
+	return [...available].sort((left, right) => left - right).find((episode) => !watched.has(episode)) ?? null;
+}
+
+export function neighboringEpisodes(available: readonly number[], episode: number): { previous: number | null; next: number | null } {
+	const sorted = [...available].sort((left, right) => left - right);
+	const index = sorted.indexOf(episode);
+	return index < 0
+		? { previous: sorted.filter((candidate) => candidate < episode).at(-1) ?? null, next: sorted.find((candidate) => candidate > episode) ?? null }
+		: { previous: index > 0 ? sorted[index - 1]! : null, next: index + 1 < sorted.length ? sorted[index + 1]! : null };
+}
+
+export function nextUnwatchedEntry(
+	entries: readonly MediaEntry[],
+	watched: ReadonlySet<string>,
+): MediaEntry | null {
+	return entries.find((entry) => !watched.has(entry.id)) ?? null;
+}
+
+export function neighboringEntries(
+	entries: readonly MediaEntry[],
+	currentId: string,
+): { previous: MediaEntry | null; next: MediaEntry | null } {
+	const index = entries.findIndex((entry) => entry.id === currentId);
+	return index < 0
+		? { previous: null, next: entries[0] ?? null }
+		: {
+				previous: index > 0 ? entries[index - 1]! : null,
+				next: index + 1 < entries.length ? entries[index + 1]! : null,
+		  };
+}
+
+export function sortMediaEntries(entries: readonly MediaEntry[]): MediaEntry[] {
+	return [...entries].sort((left, right) => {
+		const leftSeason = left.season ?? Number.MAX_SAFE_INTEGER;
+		const rightSeason = right.season ?? Number.MAX_SAFE_INTEGER;
+		return leftSeason - rightSeason || (left.episode ?? left.volume ?? Number.MAX_SAFE_INTEGER) - (right.episode ?? right.volume ?? Number.MAX_SAFE_INTEGER) || left.id.localeCompare(right.id);
+	});
+}

package/src/player.ts

@@ -0,0 +1,45 @@
+import type { MediaSource } from "./work";
+
+export type PlayerFormat = "mp4" | "webm" | "hls" | "dash" | "embed" | "page";
+
+export function inferPlayerFormat(url: string): PlayerFormat {
+	const path = url.split(/[?#]/, 1)[0]!.toLowerCase();
+	if (path.endsWith(".m3u8") || path.endsWith(".m3u")) return "hls";
+	if (path.endsWith(".mpd")) return "dash";
+	if (path.endsWith(".webm")) return "webm";
+	if (path.endsWith(".mp4")) return "mp4";
+	return "embed";
+}
+
+export function sourcePlayerUrl(source: MediaSource, startSeconds = 0): string {
+	if (source.platform === "youtube") {
+		const params = new URLSearchParams({ rel: "0", modestbranding: "1" });
+		if (startSeconds > 0) params.set("start", String(Math.floor(startSeconds)));
+		return `https://www.youtube-nocookie.com/embed/${source.id}?${params}`;
+	}
+	if (source.platform === "dailymotion") {
+		const params = new URLSearchParams({ "queue-enable": "false", "sharing-enable": "false" });
+		if (startSeconds > 0) params.set("start", String(Math.floor(startSeconds)));
+		if (source.url.includes("/player/")) {
+			params.set("video", source.id);
+			return `${source.url.split("?")[0]}?${params}`;
+		}
+		return `https://www.dailymotion.com/embed/video/${source.id}?${params}`;
+	}
+	return source.url;
+}
+
+export function sourceFromEpisode(videoId: string, thumbnailUrl: string | null): MediaSource | null {
+	if (/^[A-Za-z0-9_-]{11}$/.test(videoId)) {
+		return { platform: "youtube", id: videoId, url: `https://www.youtube.com/watch?v=${videoId}`, official: true };
+	}
+	const dailymotionId = thumbnailUrl?.match(/dailymotion\.com\/thumbnail\/video\/([A-Za-z0-9]+)/)?.[1];
+	if (dailymotionId) {
+		return { platform: "dailymotion", id: dailymotionId, url: thumbnailUrl!, official: true };
+	}
+	return null;
+}
+
+export function sourceIsPlayable(source: MediaSource): boolean {
+	return source.platform !== "official_page" && source.platform !== "manga_publisher";
+}

package/src/runtime.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { CANONICAL_GAME_FAMILIES } from "./canon";
+import { RUST_RUNTIME_BY_MEDIA_KIND, RUST_RUNTIME_BY_PLATFORM, runtimeForPlatform } from "./runtime";
+
+describe("Rust runtime coverage", () => {
+	test("every canonical game family has a closest Rust target for every platform", () => {
+		for (const work of CANONICAL_GAME_FAMILIES) {
+			expect(work.platforms?.length).toBeGreaterThan(0);
+			expect(work.runtimeLinks?.length).toBe(work.platforms?.length);
+			expect(work.runtimeLinks?.every((runtime) => runtime.sourcePath.startsWith("crates/"))).toBeTrue();
+		}
+	});
+
+	test("platform and media matrices are total and do not fake console emulation", () => {
+		expect(Object.keys(RUST_RUNTIME_BY_PLATFORM).length).toBe(15);
+		expect(Object.values(RUST_RUNTIME_BY_PLATFORM).some((runtime) => runtime.id === "ievr-steam-emulator")).toBeTrue();
+	expect(Object.values(RUST_RUNTIME_BY_PLATFORM).filter((runtime) => runtime.executesTarget)).toHaveLength(1);
+		expect(Object.keys(RUST_RUNTIME_BY_MEDIA_KIND)).toHaveLength(5);
+		expect(runtimeForPlatform("ds").status).toBe("closest_available");
+	});
+});

package/src/runtime.ts

@@ -0,0 +1,53 @@
+import type { CanonicalMediaKind, GamePlatform, RustRuntimeLink } from "./work";
+
+const link = (
+	id: string,
+	role: RustRuntimeLink["role"],
+	crate: string,
+	sourcePath: string,
+	executesTarget: boolean,
+	status: RustRuntimeLink["status"],
+): RustRuntimeLink => ({ id, role, crate, sourcePath, executesTarget, status });
+
+/**
+ * One measured Rust bridge per platform. There is no console emulator in this repository for
+ * DS/3DS/Wii/Switch/PlayStation/Xbox/mobile; those rows deliberately point at the closest reader
+ * and remain `closest_available` instead of claiming execution support.
+ */
+export const RUST_RUNTIME_BY_PLATFORM: Readonly<Record<GamePlatform, RustRuntimeLink>> = {
+	ds: link("ds-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	"3ds": link("3ds-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	wii: link("wii-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	switch: link("switch-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	switch_2: link("switch-2-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	ps4: link("ps4-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	ps5: link("ps5-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	playstation: link("playstation-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	xbox: link("xbox-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	pc: link("ievr-steam-emulator", "emulator", "nie-steam", "crates/tools/nie-steam/src/emulator.rs", true, "available"),
+	ios: link("ios-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	android: link("android-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	mobile: link("mobile-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	arcade: link("arcade-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+	unknown: link("unknown-format-reader", "format_reader", "nie-formats", "crates/engine/nie-formats/src", false, "closest_available"),
+};
+
+export const RUST_RUNTIME_BY_MEDIA_KIND: Readonly<Record<CanonicalMediaKind, RustRuntimeLink>> = {
+	episode: link("episode-catalog", "catalog", "nie-sql", "../iecode/src/niers/nie-sql/src", false, "closest_available"),
+	film: link("vfs-film-player", "media_player", "nie-explore", "crates/engine/nie-explore/src/cinema/browser_video.rs", true, "available"),
+	game_video: link("vfs-game-video-player", "media_player", "nie-explore", "crates/engine/nie-explore/src/native_video.rs", true, "available"),
+	manga_volume: link("manga-catalog", "catalog", "nie-site", "crates/tools/nie-site/src", false, "closest_available"),
+	special: link("special-media-catalog", "catalog", "nie-site", "crates/tools/nie-site/src", false, "closest_available"),
+};
+
+export function runtimeForPlatform(platform: GamePlatform): RustRuntimeLink {
+	return RUST_RUNTIME_BY_PLATFORM[platform];
+}
+
+export function runtimeForMediaKind(kind: CanonicalMediaKind): RustRuntimeLink {
+	return RUST_RUNTIME_BY_MEDIA_KIND[kind];
+}
+
+export function runtimeLinksForPlatforms(platforms: readonly GamePlatform[] | undefined): RustRuntimeLink[] {
+	return (platforms ?? ["unknown"]).map(runtimeForPlatform);
+}

package/src/url.ts

@@ -0,0 +1,18 @@
+import type { CanonicalMediaKind, GameFamily, MediaEntry } from "./work";
+
+export type MediaRoute = "media" | "episodes" | "films" | "manga" | "games";
+
+export function routeForKind(kind: CanonicalMediaKind): MediaRoute {
+	if (kind === "episode") return "episodes";
+	if (kind === "film" || kind === "game_video") return "films";
+	if (kind === "manga_volume") return "manga";
+	return "media";
+}
+
+export function mediaEntryPath(entry: Pick<MediaEntry, "id" | "kind">): string {
+	return `/${routeForKind(entry.kind)}/${encodeURIComponent(entry.id)}`;
+}
+
+export function gameFamilyPath(family: GameFamily): string {
+	return `/games/${family}`;
+}

package/src/work.ts

@@ -0,0 +1,103 @@
+/** Canonical work taxonomy shared by games, animation, films, manga and specials. */
+
+export type WorkKind = "game" | "anime" | "film" | "manga" | "novel" | "special";
+
+/** Platforms and hardware families, kept separate from an individual release. */
+export type GamePlatform =
+	| "ds"
+	| "3ds"
+	| "wii"
+	| "switch"
+	| "switch_2"
+	| "ps4"
+	| "ps5"
+	| "playstation"
+	| "xbox"
+	| "pc"
+	| "ios"
+	| "android"
+	| "mobile"
+	| "arcade"
+	| "unknown";
+
+/** Canonical game families supported by the catalogue. */
+export type GameFamily =
+	| "inazuma_eleven"
+	| "inazuma_eleven_2"
+	| "inazuma_eleven_3"
+	| "inazuma_eleven_strikers"
+	| "inazuma_eleven_strikers_2012"
+	| "inazuma_eleven_strikers_2013"
+	| "inazuma_eleven_go"
+	| "inazuma_eleven_go_chrono_stones"
+	| "inazuma_eleven_go_galaxy"
+	| "inazuma_eleven_ares"
+	| "inazuma_eleven_orion"
+	| "inazuma_eleven_victory_road"
+	| "inazuma_eleven_cross"
+	| "other";
+
+export type CanonicalMediaKind = "episode" | "film" | "game_video" | "manga_volume" | "special";
+
+export type RustRuntimeRole = "emulator" | "game_runtime" | "format_reader" | "media_player" | "catalog";
+
+export interface RustRuntimeLink {
+	/** Stable identifier for the Rust capability closest to this content. */
+	id: string;
+	role: RustRuntimeRole;
+	crate: string;
+	sourcePath: string;
+	/** True only when the Rust owner actually executes the target, not merely reads it. */
+	executesTarget: boolean;
+	status: "available" | "closest_available" | "unimplemented";
+}
+
+export interface WorkRef {
+	/** Stable slug, never a translated display label. */
+	id: string;
+	kind: WorkKind;
+	title: string;
+	/** Optional official Japanese title or source title. */
+	titleOriginal?: string | null;
+	series?: GameFamily | null;
+	platforms?: readonly GamePlatform[];
+	runtimeLinks?: readonly RustRuntimeLink[];
+	order?: number | null;
+	}
+
+export interface MediaSource {
+	platform: "vfs" | "youtube" | "dailymotion" | "official_page" | "manga_publisher" | "unknown";
+	/** Stable source identifier, not a display URL. */
+	id: string;
+	url: string;
+	language?: string | null;
+	official: boolean;
+	verified?: boolean;
+	}
+
+export interface MediaEntry {
+	/** Stable deduplication key across every source and host. */
+	id: string;
+	kind: CanonicalMediaKind;
+	work: WorkRef;
+	title: string;
+	titleOriginal?: string | null;
+	season?: number | null;
+	episode?: number | null;
+	volume?: number | null;
+	chapter?: number | null;
+	date?: string | null;
+	durationSeconds?: number | null;
+	thumbnailUrl?: string | null;
+	runtime?: RustRuntimeLink;
+	sources: readonly MediaSource[];
+	}
+
+export function workId(value: string): string {
+	return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+}
+
+export function mediaId(kind: CanonicalMediaKind, work: string, ordinal?: number | null): string {
+	const suffix = ordinal == null ? "" : `_${ordinal}`;
+	return `${kind}:${workId(work)}${suffix}`;
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "../../tsconfig.niers-base.json",
+	"include": ["src/**/*.ts", "src/**/*.tsx"]
+}