@hoardodile/sdk-types 0.0.0

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@hoardodile/sdk-types",
+  "version": "0.0.0",
+  "license": "MIT",
+  "description": "Plugin manifest contract, shared types and constants for hoardodile content plugins.",
+  "keywords": [
+    "hoardodile",
+    "plugin",
+    "sdk",
+    "types",
+    "manifest",
+    "constants"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hoardodile/hoardodile.git",
+    "directory": "plugins/sdk-types"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./image-variant": {
+      "types": "./dist/image-variant.d.ts",
+      "development": "./src/image-variant.ts",
+      "default": "./dist/image-variant.js"
+    },
+    "./media-exts": {
+      "types": "./dist/media-exts.d.ts",
+      "development": "./src/media-exts.ts",
+      "default": "./dist/media-exts.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "development": "./src/plugin.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./plugin-asset-limits": {
+      "types": "./dist/plugin-asset-limits.d.ts",
+      "development": "./src/plugin-asset-limits.ts",
+      "default": "./dist/plugin-asset-limits.js"
+    },
+    "./plugin-capabilities": {
+      "types": "./dist/plugin-capabilities.d.ts",
+      "development": "./src/plugin-capabilities.ts",
+      "default": "./dist/plugin-capabilities.js"
+    },
+    "./resource": {
+      "types": "./dist/resource.d.ts",
+      "development": "./src/resource.ts",
+      "default": "./dist/resource.js"
+    },
+    "./result": {
+      "types": "./dist/result.d.ts",
+      "development": "./src/result.ts",
+      "default": "./dist/result.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "development": "./src/schema.ts",
+      "default": "./dist/schema.js"
+    },
+    "./template": {
+      "types": "./dist/template.d.ts",
+      "development": "./src/template.ts",
+      "default": "./dist/template.js"
+    },
+    "./text-limits": {
+      "types": "./dist/text-limits.d.ts",
+      "development": "./src/text-limits.ts",
+      "default": "./dist/text-limits.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --maxWorkers=2"
+  }
+}

package/src/file-list.ts

@@ -0,0 +1,14 @@
+/**
+ * One item in a serialized file list: a bare filename string or a
+ * metadata object. Object entries carry `filename` plus any extra
+ * fields; the host renders covers and chips from this shape.
+ */
+export type SerializedFileEntry =
+	| string
+	| Record<string, string | number | boolean>
+
+/**
+ * Serialized file list as stored in the sidecar cache and sent over the
+ * wire. Order is the display order; the host preserves it verbatim.
+ */
+export type SerializedFileList = readonly SerializedFileEntry[]

package/src/image-variant.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "vitest"
+import {
+	imageVariantCanonical,
+	imageVariantQuery,
+	normalizeImageVariantSpec,
+	parseImageVariantQuery,
+} from "./image-variant.ts"
+import { RESOURCE_PREVIEW_MAX_AREA } from "./resource.ts"
+
+const QUALITY_DEFAULTS = { avifQuality: 65, webpQuality: 90 }
+
+describe("parseImageVariantQuery", () => {
+	test("no variant parameters means the original", () => {
+		expect(parseImageVariantQuery({})).toEqual({ kind: "none" })
+		expect(parseImageVariantQuery({ size: "original" })).toEqual({
+			kind: "none",
+		})
+	})
+
+	test("size=preview alone requests the default variant", () => {
+		expect(parseImageVariantQuery({ size: "preview" })).toEqual({
+			kind: "variant",
+			spec: {},
+		})
+	})
+
+	test("any variant parameter requests a variant", () => {
+		const result = parseImageVariantQuery({
+			size: "preview",
+			fmt: "webp",
+			fit: "exact",
+			area: "2000000",
+			q: "80",
+		})
+		expect(result).toEqual({
+			kind: "variant",
+			spec: { format: "webp", fit: "exact", maxArea: 2000000, quality: 80 },
+		})
+	})
+
+	test("numeric strings are coerced", () => {
+		expect(parseImageVariantQuery({ area: "4000000", q: 50 })).toEqual({
+			kind: "variant",
+			spec: { maxArea: 4000000, quality: 50 },
+		})
+	})
+
+	test("invalid format, fit, area and quality are rejected", () => {
+		expect(parseImageVariantQuery({ fmt: "png" })).toMatchObject({
+			kind: "invalid",
+		})
+		expect(parseImageVariantQuery({ fit: "cover" })).toMatchObject({
+			kind: "invalid",
+		})
+		expect(parseImageVariantQuery({ area: "0" })).toMatchObject({
+			kind: "invalid",
+		})
+		expect(parseImageVariantQuery({ area: "1.5" })).toMatchObject({
+			kind: "invalid",
+		})
+		expect(parseImageVariantQuery({ q: "101" })).toMatchObject({
+			kind: "invalid",
+		})
+		expect(parseImageVariantQuery({ q: "abc" })).toMatchObject({
+			kind: "invalid",
+		})
+	})
+})
+
+describe("normalizeImageVariantSpec", () => {
+	test("empty spec fills every default", () => {
+		expect(normalizeImageVariantSpec({}, QUALITY_DEFAULTS)).toEqual({
+			format: "avif",
+			fit: "inside",
+			maxArea: RESOURCE_PREVIEW_MAX_AREA,
+			avifQuality: 65,
+			webpQuality: 90,
+		})
+	})
+
+	test("quality maps onto both per-format qualities", () => {
+		const resolved = normalizeImageVariantSpec(
+			{ format: "webp", fit: "exact", quality: 80 },
+			QUALITY_DEFAULTS,
+		)
+		expect(resolved).toEqual({
+			format: "webp",
+			fit: "exact",
+			maxArea: RESOURCE_PREVIEW_MAX_AREA,
+			avifQuality: 80,
+			webpQuality: 80,
+		})
+	})
+
+	test("out-of-range values are clamped, not rejected", () => {
+		const resolved = normalizeImageVariantSpec(
+			{ maxArea: 0, quality: 500 },
+			QUALITY_DEFAULTS,
+		)
+		expect(resolved.maxArea).toBe(1)
+		expect(resolved.avifQuality).toBe(100)
+		expect(resolved.webpQuality).toBe(100)
+	})
+})
+
+describe("imageVariantCanonical", () => {
+	test("identical variants share one canonical string", () => {
+		const a = normalizeImageVariantSpec(
+			{ format: "webp", fit: "exact", quality: 80 },
+			QUALITY_DEFAULTS,
+		)
+		// The explicit area equals the default, so both requests render
+		// identically and must share a cache identity.
+		const b = normalizeImageVariantSpec(
+			{
+				format: "webp",
+				fit: "exact",
+				maxArea: RESOURCE_PREVIEW_MAX_AREA,
+				quality: 80,
+			},
+			QUALITY_DEFAULTS,
+		)
+		expect(imageVariantCanonical(a)).toBe(imageVariantCanonical(b))
+	})
+
+	test("different qualities diverge", () => {
+		const a = normalizeImageVariantSpec({ quality: 80 }, QUALITY_DEFAULTS)
+		const b = normalizeImageVariantSpec({ quality: 81 }, QUALITY_DEFAULTS)
+		expect(imageVariantCanonical(a)).not.toBe(imageVariantCanonical(b))
+	})
+})
+
+describe("imageVariantQuery", () => {
+	test("always carries size=preview so old servers degrade safely", () => {
+		expect(imageVariantQuery({})).toBe("size=preview")
+		expect(
+			imageVariantQuery({ format: "webp", fit: "exact", quality: 80 }),
+		).toBe("size=preview&fmt=webp&fit=exact&q=80")
+	})
+})

package/src/image-variant.ts

@@ -0,0 +1,234 @@
+/**
+ * Image variant contract: how a plugin asks the host to derive an image
+ * from a resource file, and how that request travels on the wire.
+ *
+ * One {@link ImageVariantSpec} has three projections, all derived from
+ * this module:
+ *
+ * - the URL query (`imageVariantQuery`) the iframe client emits,
+ * - the resolved render spec (`normalizeImageVariantSpec`) the
+ *   pipelines execute,
+ * - the canonical cache identity (`imageVariantCanonical`) that keys
+ *   the on-disk caches.
+ *
+ * The per-format encode qualities are pipeline constants, not part of
+ * the wire contract — callers fill them in at the render boundary, so
+ * this module stays dependency-free and browser-safe.
+ */
+import { RESOURCE_PREVIEW_MAX_AREA } from "./resource.ts"
+
+export const IMAGE_VARIANT_FORMATS = ["avif", "webp"] as const
+export type ImageVariantFormat = (typeof IMAGE_VARIANT_FORMATS)[number]
+
+/**
+ * How the source image is fitted into the variant:
+ * - `inside` — downscaled (never upscaled) to fit within `maxArea`;
+ * - `exact` — transcode only: output pixels are exactly the source
+ *   dimensions (needed when downstream code maps coordinates onto the
+ *   texture, e.g. Live2D models).
+ */
+export const IMAGE_VARIANT_FITS = ["inside", "exact"] as const
+export type ImageVariantFit = (typeof IMAGE_VARIANT_FITS)[number]
+
+/** Upper bound for the `area` query param (bounded cache-key space). */
+export const IMAGE_VARIANT_MAX_AREA = 1_000_000_000
+
+/** Encode-quality range for the `q` query param. */
+export const IMAGE_VARIANT_MIN_QUALITY = 1
+export const IMAGE_VARIANT_MAX_QUALITY = 100
+
+/**
+ * Client-declared variant request. Every field is optional; omitted
+ * fields fall back to the defaults (`format` avif, `fit` inside,
+ * `maxArea` {@link RESOURCE_PREVIEW_MAX_AREA}, per-format quality).
+ * `maxArea` only has an effect when `fit` is `inside`; it is carried
+ * through (and cached under) regardless so URL identity stays stable.
+ */
+export type ImageVariantSpec = {
+	readonly format?: ImageVariantFormat
+	readonly fit?: ImageVariantFit
+	readonly maxArea?: number
+	readonly quality?: number
+}
+
+/**
+ * A fully resolved variant: every field concrete, including the
+ * per-format encode qualities the pipeline consumes. This is the render
+ * boundary shape and the input to {@link imageVariantCanonical}.
+ */
+export type ResolvedImageVariant = {
+	readonly format: ImageVariantFormat
+	readonly fit: ImageVariantFit
+	readonly maxArea: number
+	readonly webpQuality: number
+	readonly avifQuality: number
+}
+
+/** Query parameters accepted by the resource file route. */
+export type ImageVariantQuery = {
+	readonly size?: string
+	readonly fmt?: string
+	readonly fit?: string
+	readonly area?: string | number
+	readonly q?: string | number
+}
+
+export type ImageVariantParseResult =
+	| { readonly kind: "none" }
+	| { readonly kind: "variant"; readonly spec: ImageVariantSpec }
+	| { readonly kind: "invalid"; readonly reason: string }
+
+export function isImageVariantFormat(
+	value: string,
+): value is ImageVariantFormat {
+	return IMAGE_VARIANT_FORMATS.some((format) => format === value)
+}
+
+export function isImageVariantFit(value: string): value is ImageVariantFit {
+	return IMAGE_VARIANT_FITS.some((fit) => fit === value)
+}
+
+/**
+ * Interpret the file route's query. A variant is requested when
+ * `size=preview` (the compatibility alias) or any variant parameter is
+ * present; otherwise the route serves the original bytes.
+ * Returns `invalid` for out-of-range or malformed values.
+ */
+export function parseImageVariantQuery(
+	query: ImageVariantQuery,
+): ImageVariantParseResult {
+	const requested =
+		query.size === "preview" ||
+		query.fmt !== undefined ||
+		query.fit !== undefined ||
+		query.area !== undefined ||
+		query.q !== undefined
+	if (!requested) return { kind: "none" }
+
+	let format: ImageVariantFormat | undefined
+	let fit: ImageVariantFit | undefined
+	let maxArea: number | undefined
+	let quality: number | undefined
+	if (query.fmt !== undefined) {
+		if (!isImageVariantFormat(query.fmt)) {
+			return invalidFormat(query.fmt)
+		}
+		format = query.fmt
+	}
+	if (query.fit !== undefined) {
+		if (!isImageVariantFit(query.fit)) {
+			return invalidFit(query.fit)
+		}
+		fit = query.fit
+	}
+	if (query.area !== undefined) {
+		const area = parseVariantInteger(query.area, IMAGE_VARIANT_MAX_AREA)
+		if (area === undefined) return invalidArea(query.area)
+		maxArea = area
+	}
+	if (query.q !== undefined) {
+		const q = parseVariantInteger(query.q, IMAGE_VARIANT_MAX_QUALITY)
+		if (q === undefined) return invalidQuality(query.q)
+		quality = q
+	}
+	return { kind: "variant", spec: { format, fit, maxArea, quality } }
+}
+
+function invalidFormat(value: string): ImageVariantParseResult {
+	return {
+		kind: "invalid",
+		reason: `invalid format "${value}" (expected ${IMAGE_VARIANT_FORMATS.join(", ")})`,
+	}
+}
+
+function invalidFit(value: string): ImageVariantParseResult {
+	return {
+		kind: "invalid",
+		reason: `invalid fit "${value}" (expected ${IMAGE_VARIANT_FITS.join(", ")})`,
+	}
+}
+
+function invalidArea(value: unknown): ImageVariantParseResult {
+	return {
+		kind: "invalid",
+		reason: `area must be an integer between 1 and ${IMAGE_VARIANT_MAX_AREA} (got "${String(value)}")`,
+	}
+}
+
+function invalidQuality(value: unknown): ImageVariantParseResult {
+	return {
+		kind: "invalid",
+		reason: `quality must be an integer between ${IMAGE_VARIANT_MIN_QUALITY} and ${IMAGE_VARIANT_MAX_QUALITY} (got "${String(value)}")`,
+	}
+}
+
+function parseVariantInteger(
+	value: string | number,
+	max: number,
+): number | undefined {
+	const num = typeof value === "number" ? value : Number(value)
+	if (!Number.isInteger(num)) return undefined
+	if (num < 1 || num > max) return undefined
+	return num
+}
+
+/**
+ * Fill the request defaults and clamp out-of-range values. `quality` is
+ * the single client knob; it maps onto both per-format pipeline
+ * qualities, which default to the caller's constants when omitted.
+ */
+export function normalizeImageVariantSpec(
+	spec: ImageVariantSpec,
+	qualityDefaults: {
+		readonly avifQuality: number
+		readonly webpQuality: number
+	},
+): ResolvedImageVariant {
+	return {
+		format: spec.format ?? "avif",
+		fit: spec.fit ?? "inside",
+		maxArea: clampArea(spec.maxArea ?? RESOURCE_PREVIEW_MAX_AREA),
+		avifQuality: clampQuality(spec.quality ?? qualityDefaults.avifQuality),
+		webpQuality: clampQuality(spec.quality ?? qualityDefaults.webpQuality),
+	}
+}
+
+function clampArea(value: number): number {
+	return Math.min(Math.max(1, Math.round(value)), IMAGE_VARIANT_MAX_AREA)
+}
+
+function clampQuality(value: number): number {
+	return Math.min(
+		Math.max(IMAGE_VARIANT_MIN_QUALITY, Math.round(value)),
+		IMAGE_VARIANT_MAX_QUALITY,
+	)
+}
+
+/**
+ * Stable string identity of a resolved variant — the cache key input.
+ * Two requests produce the same identity iff they render identically.
+ */
+export function imageVariantCanonical(variant: ResolvedImageVariant): string {
+	return [
+		variant.format,
+		variant.fit,
+		variant.maxArea,
+		variant.webpQuality,
+		variant.avifQuality,
+	].join(":")
+}
+
+/**
+ * Encode a variant request as the file route's query string. Always
+ * carries `size=preview` so an older server that does not know the
+ * variant parameters still degrades to its default preview instead of
+ * serving the original bytes.
+ */
+export function imageVariantQuery(spec: ImageVariantSpec): string {
+	const params: string[] = ["size=preview"]
+	if (spec.format !== undefined) params.push(`fmt=${spec.format}`)
+	if (spec.fit !== undefined) params.push(`fit=${spec.fit}`)
+	if (spec.maxArea !== undefined) params.push(`area=${spec.maxArea}`)
+	if (spec.quality !== undefined) params.push(`q=${spec.quality}`)
+	return params.join("&")
+}

package/src/index.ts

@@ -0,0 +1,115 @@
+/**
+ * @hoardodile/sdk-types — the plugin contract: manifest schema, the
+ * plugin definition contract (`PluginDefinition`/`ResourceAPI`/
+ * `definePlugin`/fixtures), and the shared message/danmaku/anchor wire
+ * shapes. Single source of truth consumed by every SDK package, the
+ * host, and the app; nothing here touches the DOM or node.
+ *
+ * This package is the contract — plugins normally import it for types
+ * (`PluginSchema`, `PluginManifest`, ...) and (via
+ * `@hoardodile/sdk-server`) the `definePlugin` factory. The zod
+ * runtime validators (`pluginManifest`, `anchorData`) live behind the
+ * `@hoardodile/sdk-types/schema` subpath so plugin bundles never pull
+ * zod.
+ *
+ * Plugin-facing constants (data, plus the pure lookups that read it)
+ * live in subpaths mirroring their source files — there is no root
+ * export for them:
+ *
+ * - `@hoardodile/sdk-types/image-variant` — derived-image variant
+ *   contract: spec types, query parsing/encoding, canonical cache
+ *   identity
+ * - `@hoardodile/sdk-types/media-exts` — media-type tables: extension
+ *   sets, extension ↔ MIME, MIME ↔ media kind
+ * - `@hoardodile/sdk-types/plugin` — plugin runtime limits (read cap,
+ *   probe/stat fan-out bounds)
+ * - `@hoardodile/sdk-types/resource` — resource caps (search-meta version,
+ *   preview eligibility)
+ * - `@hoardodile/sdk-types/template` — the host cover/message template
+ *   grammar (fragment splitter, tokeniser, parser — shared with the
+ *   web renderer and the CLI's build-time lint)
+ * - `@hoardodile/sdk-types/text-limits` — plugin input limits (danmaku
+ *   body, comment body)
+ *
+ * App-only constants live in `@hoardodile/shared` (infra limits) and
+ * `@hoardodile/schemas` (field lengths) instead.
+ */
+export * from "./file-list.ts"
+export type {
+	CoverKindUi,
+	CoverKindUiMap,
+	PluginManifest,
+	PluginManifestId,
+	PluginManifestUi,
+	PluginPermissions,
+	SearchKind,
+} from "./manifest.ts"
+export * from "./plugin-asset.ts"
+export * from "./plugin-definition.ts"
+export * from "./read-range.ts"
+export * from "./result.ts"
+export type { AnchorData } from "./schema.ts"
+
+/** Web plugin danmaku mode. */
+export type DanmakuMode = "scroll" | "top" | "bottom"
+
+/**
+ * Client-side danmaku list filter: every entry is matched by strict
+ * equality against the same key in the danmaku's anchor `data`. Keys are
+ * plugin-defined vocabulary (e.g. `{ kind: "videoTime", filename }` in
+ * an official content plugin) — the SDK only defines the matching semantics,
+ * not which keys exist.
+ */
+export type DanmakuListFilter = Readonly<
+	Record<string, string | number | boolean>
+>
+
+/**
+ * Anchor as returned in `Message` / `Danmaku` API shapes: the resource
+ * the anchor points into plus the plugin location payload. The server
+ * derives `resId` from the row's own `anchor_resource_id` column —
+ * plugin code never supplies it (see `anchorData` in
+ * `@hoardodile/sdk-types/schema`).
+ */
+export type ResAnchor = {
+	readonly resId: string
+	readonly data?: unknown
+}
+
+/** Web plugin message shape. */
+export type Message = {
+	readonly id: string
+	readonly parentId?: string
+	readonly body: string
+	readonly createdAt: number
+	readonly deletedAt?: number
+	readonly charIds: readonly string[]
+	readonly resIds: readonly string[]
+	readonly likeCount: number
+	readonly dislikeCount: number
+	readonly replyCount: number
+	readonly floor?: number
+	readonly anchor?: ResAnchor
+}
+
+/** Web plugin danmaku shape. */
+export type Danmaku = {
+	readonly id: string
+	readonly anchor: ResAnchor
+	readonly text: string
+	readonly color: string
+	readonly mode: DanmakuMode
+	readonly createdAt: number
+}
+
+/** Plugin-facing file stats slice of a resource. */
+export type FileStats = {
+	readonly sizeBytes?: number
+	readonly count?: number
+}
+
+/** Plugin-produced search metadata. The host enforces its own schema at ingestion time. */
+export type SearchMeta = {
+	readonly v: number
+	readonly facets?: Readonly<Record<string, boolean>>
+}