@hoardodile/sdk-types 0.0.0

package/src/plugin.ts

@@ -0,0 +1,54 @@
+/**
+ * Plugin-facing runtime limits: the read cap plugins must respect and
+ * the fan-out bounds plugins should stay within when probing. Sandbox
+ * tuning (watchdog, timeouts, memory) is app-side and lives in
+ * `@hoardodile/host` instead.
+ */
+
+/**
+ * Upper bound for a single `readFile` call, full or ranged. Anything
+ * bigger must go through byte ranges (`readFileChunks`) so neither the
+ * host process nor the plugin worker buffers it whole.
+ */
+export const PLUGIN_READ_FILE_MAX_BYTES = 128 * 1024 * 1024
+
+/**
+ * Parallel image probes a plugin hook may fan out across the host.
+ * Host-side probes run sharp concurrently; keep them bounded.
+ */
+export const PLUGIN_IMAGE_PROBE_CONCURRENCY = 8
+
+/**
+ * Parallel video probes a plugin hook may fan out. Each spawns an
+ * ffprobe process host-side, so videos are bound tighter than images.
+ */
+export const PLUGIN_VIDEO_PROBE_CONCURRENCY = 4
+
+/**
+ * Parallel audio probes a plugin hook may fan out. Shares the ffprobe
+ * spawn budget with video, so it carries the same bound.
+ */
+export const PLUGIN_AUDIO_PROBE_CONCURRENCY = 4
+
+/**
+ * How many audio files a `coverLocal` hook scans looking for embedded
+ * artwork before settling for the first audio file. Albums carry the
+ * same artwork on every track, so the scan almost always stops at the
+ * first probe; the cap keeps a pathological archive from spawning one
+ * ffprobe per track.
+ */
+export const PLUGIN_AUDIO_COVER_SCAN_LIMIT = 8
+
+/**
+ * Chunk size for batch `statFiles` calls: the host resolves each chunk
+ * in one RPC round-trip, so a 100-file archive costs ~13 round-trips
+ * instead of 100.
+ */
+export const PLUGIN_STAT_CONCURRENCY = 8
+
+/**
+ * Batch size for animation scans in `searchMeta` hooks: probes run
+ * concurrently within a batch, and the early-exit check happens between
+ * batches.
+ */
+export const PLUGIN_ANIMATION_SCAN_BATCH = 8

package/src/read-range.ts

@@ -0,0 +1,12 @@
+/**
+ * Byte range used by every file read across the plugin stack — the
+ * server-side `ResourceAPI.readFile` (see `@hoardodile/host`) and the
+ * browser-side `PluginRequests.readFile` (see `@hoardodile/sdk-web`) —
+ * so the contract lives exactly once. `start` is inclusive (default 0),
+ * `end` is exclusive (default end of file). Hosts clamp the range to the
+ * file size; a range at or past the end resolves to an empty result.
+ */
+export type ReadFileRange = {
+	readonly start?: number
+	readonly end?: number
+}

package/src/resource.ts

@@ -0,0 +1,28 @@
+/**
+ * Plugin-facing resource caps. The preview policy (`exceedsPreviewThresholds`,
+ * which consumes the two caps below) lives with its caller in
+ * `@hoardodile/sdk-server/helpers`; the cover cap below is consumed by
+ * the app's thumb pipeline, the CLI's workbench renders and the media
+ * helpers in `@hoardodile/host`. Character image-area caps stay
+ * app-internal in `@hoardodile/shared`.
+ */
+
+/**
+ * Schema version stamped onto every `SearchMeta` payload. Plugins
+ * that build search-meta MUST emit this exact value so the host can
+ * detect format drift across plugin upgrades.
+ */
+export const SEARCH_META_VERSION = 1
+
+/** Max pixel area for resource covers; larger images are scaled down. */
+export const RESOURCE_COVER_MAX_AREA = 300_000
+
+/** Max pixel area for preview variants served to resource previews. */
+export const RESOURCE_PREVIEW_MAX_AREA = 4_000_000
+
+/**
+ * Byte-size threshold for preview eligibility. An image whose
+ * area is at or below the cap may still qualify for preview when
+ * its byte size exceeds this value.
+ */
+export const RESOURCE_PREVIEW_SIZE_THRESHOLD = 1_000_000

package/src/result.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "vitest"
+import { type Detection, err, isErr, isOk, matchResult, ok } from "./index.ts"
+
+describe("ok / err", () => {
+	test("ok() yields the bare success marker", () => {
+		expect(ok()).toEqual({ ok: true })
+	})
+
+	test("err() yields the bare failure marker", () => {
+		expect(err()).toEqual({ ok: false })
+	})
+
+	test("payloads spread onto the marker", () => {
+		expect(ok({ start: 0, end: 9 })).toEqual({ ok: true, start: 0, end: 9 })
+		expect(err({ code: "bad", message: "no" })).toEqual({
+			ok: false,
+			code: "bad",
+			message: "no",
+		})
+	})
+
+	test("the plugin-facing literal stays assignable to the shared types", () => {
+		const detected: Detection = { ok: true } as const
+		expect(detected).toEqual({ ok: true })
+	})
+})
+
+describe("guards", () => {
+	test("isOk narrows the success payload", () => {
+		const result = ok({ start: 4, end: 10 })
+		expect(isOk(result)).toBe(true)
+		if (isOk(result)) {
+			expect(result.start).toBe(4)
+		}
+	})
+
+	test("isErr narrows the failure payload", () => {
+		const result = err({ code: "bad" })
+		expect(isErr(result)).toBe(true)
+		if (isErr(result)) {
+			expect(result.code).toBe("bad")
+		}
+	})
+})
+
+describe("matchResult", () => {
+	test("dispatches to the matching handler with its payload", () => {
+		const message = (r: { readonly ok: boolean }) =>
+			matchResult(r, {
+				ok: (p) => `ok ${p.ok}`,
+				err: (p) => `err ${p.ok}`,
+			})
+		expect(message(ok())).toBe("ok true")
+		expect(message(err())).toBe("err false")
+	})
+
+	test("handlers can produce a common value", () => {
+		const value = matchResult(ok({ start: 1 }), {
+			ok: (p) => p.start,
+			err: () => 0,
+		})
+		expect(value).toBe(1)
+	})
+})

package/src/result.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared `ok: true/false` result vocabulary (Rust's `Result` in spirit,
+ * spread payloads in shape): every site that answers "did it work?" —
+ * detections, parses, validations, benchmark runs — uses one type
+ * family, one pair of constructors and one pair of guards instead of
+ * hand-rolling its own union.
+ *
+ * The payloads are spread onto the marker rather than carried in a
+ * `value`/`error` channel: `ok({ start, end })` is literally
+ * `{ ok: true, start, end }`. This keeps every existing consumer's
+ * field access (`r.start`, `r.code`, `r.failure`) and every `toEqual`
+ * assertion working unchanged, and lets the plugin-facing `{ ok: true }`
+ * literal stay the contract.
+ */
+export type Ok<TPayload extends object = object> = {
+	readonly ok: true
+} & TPayload
+export type Err<TPayload extends object = object> = {
+	readonly ok: false
+} & TPayload
+export type Result<TOk extends object = object, TErr extends object = object> =
+	| Ok<TOk>
+	| Err<TErr>
+
+/**
+ * Build the success variant; `ok()` alone yields `{ ok: true }`. The
+ * cast is the constructor boundary: the runtime value is exactly
+ * `{ ok: true, ...payload }`, which the generic spread cannot prove.
+ */
+export function ok<TPayload extends object = object>(
+	payload?: TPayload,
+): Ok<TPayload> {
+	return { ok: true, ...payload } as Ok<TPayload>
+}
+
+/**
+ * Build the failure variant; `err()` alone yields `{ ok: false }`. See
+ * {@link ok} for the constructor-boundary cast.
+ */
+export function err<TPayload extends object = object>(
+	payload?: TPayload,
+): Err<TPayload> {
+	return { ok: false, ...payload } as Err<TPayload>
+}
+
+/** Narrow a result to its success variant. */
+export function isOk<TOk extends object, TErr extends object>(
+	result: Result<TOk, TErr>,
+): result is Ok<TOk> {
+	return result.ok === true
+}
+
+/** Narrow a result to its failure variant. */
+export function isErr<TOk extends object, TErr extends object>(
+	result: Result<TOk, TErr>,
+): result is Err<TErr> {
+	return result.ok === false
+}
+
+/**
+ * Destructure a result through one of two handlers — the pattern-match
+ * combinator. Both handlers must produce `R`; the chosen one receives
+ * the spread payload of its variant.
+ */
+export function matchResult<TOk extends object, TErr extends object, R>(
+	result: Result<TOk, TErr>,
+	handlers: {
+		readonly ok: (payload: Ok<TOk>) => R
+		readonly err: (payload: Err<TErr>) => R
+	},
+): R {
+	return isOk(result) ? handlers.ok(result) : handlers.err(result)
+}

package/src/schema.ts

@@ -0,0 +1,29 @@
+/**
+ * The zod schema layer of the plugin contract: the manifest schema and
+ * the wire anchor envelope. Import this subpath
+ * (`@hoardodile/sdk-types/schema`) only where a runtime validator is
+ * actually needed — the host, the server, and tooling. The root entry
+ * re-exports the inferred types only, so plugin bundles never pull zod.
+ */
+import { z } from "zod"
+
+export * from "./manifest.ts"
+
+/**
+ * Wire/storage envelope for a message or danmaku anchor. Carries only
+ * the plugin-defined location payload in `data`; the host never
+ * interprets its contents. The anchor's resource is host state — the SDK
+ * injects it from the iframe's binding and the server derives it from
+ * the row's `anchor_resource_id` column — so plugins never see a resId
+ * here, and a plugin that sends one is rejected (strict).
+ *
+ * Plugin code works with the raw location data (`PluginSchema["anchor"]`)
+ * directly; the SDK wraps it into this envelope when it crosses the
+ * wire.
+ */
+export const anchorData = z
+	.object({
+		data: z.unknown().optional(),
+	})
+	.strict()
+export type AnchorData = z.infer<typeof anchorData>

package/src/template.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, test } from "vitest"
+import {
+	parseTemplateExpression,
+	parseTemplateFragments,
+	tokeniseExpression,
+} from "./template.ts"
+
+describe("parseTemplateFragments", () => {
+	test("splits text and expressions, keeping the {{ }} contents", () => {
+		expect(parseTemplateFragments("P{{file.count}}Q{{t('x')}}")).toEqual([
+			{ kind: "text", value: "P" },
+			{ kind: "expr", source: "file.count" },
+			{ kind: "text", value: "Q" },
+			{ kind: "expr", source: "t('x')" },
+		])
+	})
+
+	test("handles pure text and unbalanced fragments gracefully", () => {
+		expect(parseTemplateFragments("plain")).toEqual([
+			{ kind: "text", value: "plain" },
+		])
+		expect(parseTemplateFragments("{{unclosed")).toEqual([
+			{ kind: "text", value: "{{unclosed" },
+		])
+	})
+})
+
+describe("tokeniseExpression", () => {
+	test("emits the full token vocabulary", () => {
+		const tokens = tokeniseExpression("join(' ', a.b, gt(x, 1))")
+		expect(tokens.map((t) => t.kind)).toEqual([
+			"ident",
+			"lparen",
+			"string",
+			"comma",
+			"ident",
+			"dot",
+			"ident",
+			"comma",
+			"ident",
+			"lparen",
+			"ident",
+			"comma",
+			"ident",
+			"rparen",
+			"rparen",
+			"eof",
+		])
+	})
+})
+
+describe("parseTemplateExpression", () => {
+	test("parses paths", () => {
+		expect(parseTemplateExpression("file.count")).toEqual({
+			kind: "path",
+			segments: ["file", "count"],
+		})
+	})
+
+	test("parses calls with nested args", () => {
+		expect(parseTemplateExpression("if(gt(file.count, 1), t('x'))")).toEqual({
+			kind: "call",
+			name: "if",
+			args: [
+				{
+					kind: "expr",
+					expr: {
+						kind: "call",
+						name: "gt",
+						args: [
+							{
+								kind: "expr",
+								expr: { kind: "path", segments: ["file", "count"] },
+							},
+							{ kind: "expr", expr: { kind: "path", segments: ["1"] } },
+						],
+					},
+				},
+				{
+					kind: "expr",
+					expr: {
+						kind: "call",
+						name: "t",
+						args: [{ kind: "string", value: "x" }],
+					},
+				},
+			],
+		})
+	})
+
+	test("recovers from a missing closing paren with a partial AST", () => {
+		expect(parseTemplateExpression("if(gt(a, b")).toEqual({
+			kind: "call",
+			name: "if",
+			args: [
+				{
+					kind: "expr",
+					expr: {
+						kind: "call",
+						name: "gt",
+						args: [
+							{ kind: "expr", expr: { kind: "path", segments: ["a"] } },
+							{ kind: "expr", expr: { kind: "path", segments: ["b"] } },
+						],
+					},
+				},
+			],
+		})
+	})
+
+	test("fails on non-identifier heads", () => {
+		expect(parseTemplateExpression("(x)")).toBeUndefined()
+		expect(parseTemplateExpression("'str'")).toBeUndefined()
+		expect(parseTemplateExpression("")).toBeUndefined()
+	})
+})

package/src/template.ts

@@ -0,0 +1,199 @@
+/**
+ * The host's cover/message template grammar: fragment splitting, the
+ * expression tokeniser and the recursive-descent parser. Pure logic
+ * with no DOM or React — shared verbatim by the web renderer
+ * (`apps/web/src/features/res/template/render.ts`) and the CLI's
+ * build-time template lint (`packages/cli`), so the linter can never
+ * drift from what the engine actually renders.
+ *
+ * The parser is deliberately lenient: a partial parse recovers and the
+ * evaluator renders what it can (bad expressions render as the empty
+ * string). Strictness belongs to the lint tooling, which inspects the
+ * tokens and the AST on top of this grammar.
+ */
+
+const TEMPLATE_RE = /\{\{(.*?)\}\}/g
+
+export type TemplateFragment =
+	| { readonly kind: "text"; readonly value: string }
+	| { readonly kind: "expr"; readonly source: string }
+
+/** Split a template into literal text and `{{...}}` expression fragments. */
+export function parseTemplateFragments(
+	template: string,
+): readonly TemplateFragment[] {
+	const fragments: TemplateFragment[] = []
+	let lastIndex = 0
+	for (const match of template.matchAll(TEMPLATE_RE)) {
+		const start = match.index ?? 0
+		if (start > lastIndex) {
+			fragments.push({ kind: "text", value: template.slice(lastIndex, start) })
+		}
+		fragments.push({ kind: "expr", source: match[1] ?? "" })
+		lastIndex = start + match[0].length
+	}
+	if (lastIndex < template.length) {
+		fragments.push({ kind: "text", value: template.slice(lastIndex) })
+	}
+	return fragments
+}
+
+export type TemplateToken =
+	| { readonly kind: "ident"; readonly value: string }
+	| { readonly kind: "dot" }
+	| { readonly kind: "lparen" }
+	| { readonly kind: "rparen" }
+	| { readonly kind: "comma" }
+	| { readonly kind: "string"; readonly value: string }
+	| { readonly kind: "eof" }
+
+/** Tokenise one expression body (the inside of `{{...}}`). */
+export function tokeniseExpression(source: string): TemplateToken[] {
+	const tokens: TemplateToken[] = []
+	let i = 0
+	while (i < source.length) {
+		const ch = source[i]!
+		if (/\s/.test(ch)) {
+			i++
+			continue
+		}
+		if (ch === ".") {
+			tokens.push({ kind: "dot" })
+			i++
+			continue
+		}
+		if (ch === "(") {
+			tokens.push({ kind: "lparen" })
+			i++
+			continue
+		}
+		if (ch === ")") {
+			tokens.push({ kind: "rparen" })
+			i++
+			continue
+		}
+		if (ch === ",") {
+			tokens.push({ kind: "comma" })
+			i++
+			continue
+		}
+		if (ch === "'") {
+			let j = i + 1
+			while (j < source.length && source[j] !== "'") {
+				j++
+			}
+			tokens.push({ kind: "string", value: source.slice(i + 1, j) })
+			i = j + 1
+			continue
+		}
+		if (/[A-Za-z0-9_]/.test(ch)) {
+			let j = i
+			while (j < source.length && /[A-Za-z0-9_]/.test(source[j]!)) {
+				j++
+			}
+			tokens.push({ kind: "ident", value: source.slice(i, j) })
+			i = j
+			continue
+		}
+		// Unrecognised character — skip; the evaluator renders the
+		// resulting expression as the empty string.
+		i++
+	}
+	tokens.push({ kind: "eof" })
+	return tokens
+}
+
+export type TemplateExpr =
+	| { readonly kind: "path"; readonly segments: readonly string[] }
+	| {
+			readonly kind: "call"
+			readonly name: string
+			readonly args: readonly TemplateArg[]
+	  }
+
+export type TemplateArg =
+	| { readonly kind: "expr"; readonly expr: TemplateExpr }
+	| { readonly kind: "string"; readonly value: string }
+
+class Parser {
+	readonly tokens: TemplateToken[]
+	pos = 0
+	constructor(tokens: TemplateToken[]) {
+		this.tokens = tokens
+	}
+
+	peek(): TemplateToken {
+		return this.tokens[this.pos] ?? { kind: "eof" }
+	}
+
+	advance(): TemplateToken {
+		const t = this.tokens[this.pos]
+		this.pos++
+		return t ?? { kind: "eof" }
+	}
+}
+
+function parseExpr(parser: Parser): TemplateExpr | undefined {
+	const t = parser.peek()
+	if (t.kind !== "ident") return undefined
+	parser.advance()
+
+	const next = parser.peek()
+	if (next.kind === "lparen") {
+		// call
+		parser.advance() // consume (
+		const args: TemplateArg[] = []
+		if (parser.peek().kind !== "rparen") {
+			while (true) {
+				const arg = parseArg(parser)
+				if (arg === undefined) break
+				args.push(arg)
+				if (parser.peek().kind === "comma") {
+					parser.advance()
+					continue
+				}
+				break
+			}
+		}
+		if (parser.peek().kind === "rparen") {
+			parser.advance()
+		}
+		return { kind: "call", name: t.value, args }
+	}
+
+	// path
+	const segments = [t.value]
+	while (parser.peek().kind === "dot") {
+		parser.advance()
+		const seg = parser.peek()
+		if (seg.kind !== "ident") break
+		parser.advance()
+		segments.push(seg.value)
+	}
+	return { kind: "path", segments }
+}
+
+function parseArg(parser: Parser): TemplateArg | undefined {
+	const t = parser.peek()
+	if (t.kind === "string") {
+		parser.advance()
+		return { kind: "string", value: t.value }
+	}
+	const expr = parseExpr(parser)
+	if (expr === undefined) return undefined
+	return { kind: "expr", expr }
+}
+
+/**
+ * Parse one expression body (`{{...}}` contents) into an AST. Returns
+ * `undefined` when the expression does not start with an identifier —
+ * a call or path head is required. Note the parser is lenient about
+ * the *tail*: unbalanced parentheses recover into a partial AST (the
+ * evaluator renders what it can); use {@link tokeniseExpression} and
+ * check paren balance yourself when strictness matters.
+ */
+export function parseTemplateExpression(
+	source: string,
+): TemplateExpr | undefined {
+	return parseExpr(new Parser(tokeniseExpression(source)))
+}

package/src/text-limits.ts

@@ -0,0 +1,11 @@
+/**
+ * Plugin-facing text-length limits: the input caps plugins that render
+ * composers need. App-side field limits live in
+ * `@hoardodile/schemas/text-limits` instead.
+ */
+
+/** Danmaku body cap enforced by the host. */
+export const MAX_DANMAKU_TEXT_LENGTH = 100
+
+/** Comment/message body cap enforced by the host. */
+export const MAX_COMMENT_BODY_LENGTH = 10_000