@vestra-player/sdk 1.5.9 → 1.5.12

package/dist/i18n.js

@@ -8,6 +8,8 @@
  * Internal: the player's runner and tests reach it through
  * `@vestra-player/sdk/runtime`, `LOCALES` through `./testing`.
  */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 /**
  * The player's interface languages: English (the source language) first,
  * then the translations, as the player's own table (its tests check that
@@ -326,6 +328,254 @@ export function placeholders(text) {
         found.push(match[1]);
     return found.sort();
 }
+// ---------------------------------------------------------------- texts
+/**
+ * The ways a `TextList` is joined (`ListStyle`), as the player
+ * joins them in each interface language (`LIST_SEPARATORS`).
+ */
+export const LIST_STYLES = [
+    "list",
+    "clauses",
+    "semicolons",
+    "sentences",
+    "lines",
+];
+/**
+ * The separator of each list style per interface language, as the player's
+ * table (`i18n::text::SEPARATORS`; its tests check that they agree).
+ */
+export const LIST_SEPARATORS = {
+    en: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    "zh-Hans": {
+        list: "、",
+        clauses: "，",
+        semicolons: "；",
+        sentences: "。",
+        lines: "\n",
+    },
+    ja: {
+        list: "、",
+        clauses: "、",
+        semicolons: "；",
+        sentences: "。",
+        lines: "\n",
+    },
+    ko: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    de: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    fr: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: " ; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    es: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+};
+/**
+ * The player's limits on one text value (a
+ * {@link @vestra-player/sdk!Text | Text} or
+ * {@link @vestra-player/sdk!TextList | TextList} with everything nested in it), as the player's
+ * `i18n::text` (its tests check that they agree).
+ */
+export const TEXT_LIMITS = {
+    /** Nesting depth of texts and lists; the value itself is depth 0 (8). */
+    depth: 8,
+    /** Texts, lists and arguments in all, the value itself included (1024). */
+    nodes: 1024,
+    /** Arguments of one text (16). */
+    args: 16,
+    /** Items of one list (256). */
+    items: 256,
+    /** UTF-8 bytes of a source text or a string argument (4096). */
+    stringBytes: 4096,
+};
+const plainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** A text or list value (by its marker key). */
+export function isTextValue(value) {
+    return (plainObject(value) && ("$vestraText" in value || "$vestraList" in value));
+}
+const utf8 = (text) => new TextEncoder().encode(text).length;
+/**
+ * Why the player would refuse a text value or template arguments, or
+ * `null`. `args` mode checks template arguments (an array or object of
+ * arguments) instead of one value. The same rules and messages as the
+ * player's `i18n::text::check`.
+ */
+export function textProblem(value, mode = "value") {
+    let nodes = 0;
+    const L = TEXT_LIMITS;
+    const args = (list, depth) => {
+        const values = Array.isArray(list)
+            ? list
+            : plainObject(list)
+                ? Object.values(list)
+                : null;
+        if (!values)
+            return "args is an array or an object";
+        if (values.length > L.args)
+            return `args holds at most ${L.args} values`;
+        for (const item of values) {
+            const problem = arg(item, depth);
+            if (problem)
+                return problem;
+        }
+        return null;
+    };
+    const arg = (item, depth) => {
+        if (typeof item === "number")
+            return Number.isFinite(item) ? count() : "a number argument is finite";
+        if (typeof item === "string")
+            return utf8(item) > L.stringBytes
+                ? `a string argument is at most ${L.stringBytes} bytes`
+                : count();
+        if (isTextValue(item))
+            return text(item, depth + 1);
+        return "args are strings, numbers, texts and lists";
+    };
+    const count = () => ++nodes > L.nodes ? `a text holds at most ${L.nodes} values` : null;
+    const text = (item, depth) => {
+        if (depth > L.depth)
+            return `texts nest at most ${L.depth} deep`;
+        if (!plainObject(item))
+            return "a text is a $vestraText or $vestraList object";
+        const over = count();
+        if (over)
+            return over;
+        if ("$vestraText" in item) {
+            const keys = Object.keys(item);
+            if (keys.some((key) => key !== "$vestraText" && key !== "args"))
+                return "a text has only $vestraText and args";
+            const source = item.$vestraText;
+            if (typeof source !== "string" || source === "")
+                return "a text's source is a non-empty string";
+            if (utf8(source) > L.stringBytes)
+                return `a text's source is at most ${L.stringBytes} bytes`;
+            return item.args === undefined ? null : args(item.args, depth);
+        }
+        const keys = Object.keys(item);
+        if (keys.some((key) => key !== "$vestraList" && key !== "style"))
+            return "a list has only $vestraList and style";
+        const items = item.$vestraList;
+        if (!Array.isArray(items))
+            return "a list's items are an array";
+        if (items.length > L.items)
+            return `a list holds at most ${L.items} items`;
+        if (item.style !== undefined &&
+            !LIST_STYLES.includes(item.style))
+            return `a list's style is one of ${LIST_STYLES.join(", ")}`;
+        for (const entry of items) {
+            const problem = arg(entry, depth);
+            if (problem)
+                return problem;
+        }
+        return null;
+    };
+    return mode === "args" ? args(value, 0) : text(value, 0);
+}
+function renderArg(arg, r) {
+    return isTextValue(arg) ? renderValue(arg, r) : arg;
+}
+function renderValue(value, r) {
+    if ("$vestraText" in value) {
+        const template = r.catalog.text(value.$vestraText);
+        return format(template, renderArgs(value.args, r) ?? []);
+    }
+    const locale = LOCALES.includes(r.locale)
+        ? r.locale
+        : "en";
+    const separator = LIST_SEPARATORS[locale][value.style ?? "list"];
+    return value.$vestraList
+        .map((item) => String(argumentText(renderArg(item, r))))
+        .join(separator);
+}
+const argumentText = (value) => typeof value === "number" ? format("{}", [value]) : value;
+function renderArgs(args, r) {
+    if (args === undefined || args === null)
+        return undefined;
+    if (Array.isArray(args))
+        return args.map((arg) => renderArg(arg, r));
+    return Object.fromEntries(Object.entries(args).map(([name, arg]) => [name, renderArg(arg, r)]));
+}
+/**
+ * A text value as the player shows it: the source translated with the
+ * plugin's catalog and formatted with its (rendered) arguments; a list's
+ * items joined with the locale's separator.
+ */
+export function renderText(value, catalog, locale) {
+    return renderValue(value, { catalog, locale });
+}
+/**
+ * Template arguments with their texts rendered (for `format`): what the
+ * player fills a template with.
+ */
+export function renderTemplateArgs(args, catalog, locale) {
+    return renderArgs(args ?? undefined, { catalog, locale });
+}
+/** The English rendering of a text value: the key a menu merges by. */
+export function textKey(value) {
+    return renderValue(value, { catalog: new Catalog(), locale: "en" });
+}
+/**
+ * A property value with every text value in it replaced by its shown
+ * string, as the player does before it hands the value to Slint. Returns
+ * a problem (`textProblem`) instead when a text value is malformed.
+ */
+export function resolveTexts(value, catalog, locale) {
+    let problem = null;
+    const walk = (item) => {
+        if (problem)
+            return item;
+        if (isTextValue(item)) {
+            problem = textProblem(item);
+            return problem ? item : renderText(item, catalog, locale);
+        }
+        if (Array.isArray(item))
+            return item.map(walk);
+        if (plainObject(item)) {
+            // A runtime image or Markdown document stays as it is.
+            if ("$vestraImage" in item || "$vestraMarkdown" in item)
+                return item;
+            return Object.fromEntries(Object.entries(item).map(([key, entry]) => [key, walk(entry)]));
+        }
+        return item;
+    };
+    const out = walk(value);
+    return problem ? { problem } : { value: out };
+}
+/** Whether a value holds a text value anywhere (a cheap pre-check). */
+export function hasTexts(value) {
+    if (isTextValue(value))
+        return true;
+    if (Array.isArray(value))
+        return value.some(hasTexts);
+    if (plainObject(value))
+        return Object.values(value).some(hasTexts);
+    return false;
+}
 const lineEnd = (s, i) => {
     const found = s.slice(i).search(/[\n\r]/);
     return found < 0 ? s.length : i + found;
@@ -671,3 +921,52 @@ export const HOST_ZH_HANS = {
     "Not available in fullscreen": "全屏时不可用",
     "Picture-in-picture is not supported on this system": "此系统不支持画中画",
 };
+// ---------------------------------------------------------------- packages
+/**
+ * The catalog of a package directory for `locale`, as the player loads it:
+ * the compiled `locales/<lang>.json` of a built package, else the source
+ * `locales/<lang>.po`. Empty for English and without a file; a broken file
+ * throws.
+ */
+export function loadPackageCatalog(directory, locale) {
+    if (locale === "en")
+        return new Catalog();
+    const base = join(directory, "locales", locale);
+    if (existsSync(`${base}.json`)) {
+        const compiled = JSON.parse(readFileSync(`${base}.json`, "utf8"));
+        return new Catalog(compiled.messages ?? {});
+    }
+    if (existsSync(`${base}.po`))
+        return new Catalog(compileCatalog(locale, parsePo(readFileSync(`${base}.po`, "utf8")).entries).messages);
+    return new Catalog();
+}
+// ---------------------------------------------------------------- columns
+const WIDE = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦\u{1F300}-\u{1F64F}\u{1F900}-\u{1F9FF}\u{20000}-\u{3FFFD}]/u;
+const ZERO = /[\p{Mn}\p{Me}​-‏]/u;
+/** Columns of one character: 2 wide (East Asian), 0 combining, else 1. */
+const columnsOf = (c) => (ZERO.test(c) ? 0 : WIDE.test(c) ? 2 : 1);
+/**
+ * Each line of `text` cut to `max` columns, ending with `…` when cut, as
+ * the player cuts an OSD panel's lines (`OsdPanelOptions.maxColumns`; the
+ * player measures with Unicode's East Asian Width, this is close to it).
+ */
+export function fitColumns(text, max) {
+    return text
+        .split("\n")
+        .map((line) => {
+        let used = 0;
+        const chars = [...line];
+        if (chars.reduce((n, c) => n + columnsOf(c), 0) <= max)
+            return line;
+        let out = "";
+        for (const c of chars) {
+            const width = columnsOf(c);
+            if (used + width > max - 1)
+                break;
+            out += c;
+            used += width;
+        }
+        return `${out}…`;
+    })
+        .join("\n");
+}

package/dist/player-runtime.d.ts

@@ -13,6 +13,7 @@ export { HostError } from "./wire.ts";
 export type { Json, Transport } from "./wire.ts";
 export { API_VERSION, CAPABILITIES } from "./capabilities.ts";
 export { COMMAND_LIMITS, MENU_IDS } from "./commands.ts";
-export { Catalog, HOST_ZH_HANS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, scanSlint, } from "./i18n.ts";
+export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.ts";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.ts";
 export { MARKDOWN_LIMITS } from "./plugin/markdown.ts";
+export { UI_VALUE_LIMITS } from "./plugin/values.ts";

package/dist/player-runtime.js

@@ -11,6 +11,7 @@ export { createPlugin } from "./plugin/index.js";
 export { HostError } from "./wire.js";
 export { API_VERSION, CAPABILITIES } from "./capabilities.js";
 export { COMMAND_LIMITS, MENU_IDS } from "./commands.js";
-export { Catalog, HOST_ZH_HANS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, scanSlint, } from "./i18n.js";
+export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.js";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.js";
 export { MARKDOWN_LIMITS } from "./plugin/markdown.js";
+export { UI_VALUE_LIMITS } from "./plugin/values.js";

package/dist/plugin/bindings.js

@@ -110,6 +110,7 @@ export const bindingsApi = (scope) => ({
                 command: info.command,
                 title: info.title,
                 path: info.path,
+                key: info.key ?? null,
                 scope: info.scope,
                 defaults: info.defaults,
                 current: info.current,

package/dist/plugin/commands.js

@@ -2,6 +2,7 @@
 import { failure, Latest, quiet } from "./runtime.js";
 import { checkBindings } from "./bindings.js";
 import { MENU_IDS } from "../commands.js";
+import { isTextValue, textProblem } from "../i18n.js";
 const value = (item) => typeof item === "function" ? item() : item;
 /** Validate options and build the wire declaration. */
 function declare(options) {
@@ -11,7 +12,18 @@ function declare(options) {
         throw failure("invalid", `command ${options.id}: title or path required`);
     if (path.length > 8)
         throw failure("invalid", `command ${options.id}: path has 1–8 segments`);
-    const menu = path[0]?.startsWith("@") ? path[0].slice(1) : null;
+    for (const segment of [title, ...path])
+        if (typeof segment !== "string") {
+            const problem = isTextValue(segment)
+                ? "$vestraList" in segment
+                    ? "a menu text is a string or a text, not a list"
+                    : textProblem(segment)
+                : "title and path segments are strings or texts";
+            if (problem)
+                throw failure("invalid", `command ${options.id}: ${problem}`);
+        }
+    const first = path[0];
+    const menu = typeof first === "string" && first.startsWith("@") ? first.slice(1) : null;
     if (menu !== null && !MENU_IDS.includes(menu))
         throw failure("invalid", `command ${options.id}: unknown menu id @${menu}; the built-in menus are ${MENU_IDS.map((id) => `@${id}`).join(", ")}`);
     if (menu !== null && path.length < 2)
@@ -21,8 +33,8 @@ function declare(options) {
         throw failure("invalid", `command ${options.id}: order must be an integer within ±1000000`);
     const bindings = [...(options.bindings ?? [])];
     return {
-        title,
-        path,
+        title: title,
+        path: path,
         order,
         group: options.group ?? "domain",
         radio: options.radio ?? false,
@@ -89,11 +101,19 @@ class CommandHandle {
         scope.add(this);
     }
     #state() {
+        const reason = value(this.#spec.reason);
+        if (reason !== null && typeof reason !== "string") {
+            const problem = isTextValue(reason)
+                ? textProblem(reason)
+                : "reason is a string, a text or null";
+            if (problem)
+                throw failure("invalid", `command ${this.id}: ${problem}`);
+        }
         return {
             enabled: value(this.#spec.enabled),
             checked: value(this.#spec.checked),
             busy: value(this.#spec.busy),
-            reason: value(this.#spec.reason),
+            reason,
         };
     }
     #sync() {

package/dist/plugin/index.js

@@ -1,4 +1,4 @@
-import { Runtime } from "./runtime.js";
+import { failure, Runtime } from "./runtime.js";
 import { ScopeImpl } from "./scope.js";
 import { playerOf } from "./player.js";
 import { windowOf } from "./window.js";
@@ -14,6 +14,14 @@ app) {
         timelineOf(runtime).init(),
     ]);
     const root = new ScopeImpl(runtime);
+    // Failures the plugin did not ask about: a property the player could not
+    // show when it rebuilt a panel or the Options window (an image removed
+    // since), a callback whose arguments it could not convert, a detached
+    // sidebar that could not be prepared. Older players send no code.
+    root.add(runtime.raw("ui.error", (data) => {
+        const { code, message } = (data ?? {});
+        root.report(failure(code ?? "ui", message ?? "user interface error"));
+    }));
     return {
         plugin: root,
         activated: () => runtime.activated(),

package/dist/plugin/language.d.ts

@@ -1,4 +1,8 @@
-/** `plugin.i18n`: the interface language of this run (read-only). */
 import type { ScopeImpl } from "./scope.ts";
-import type { I18n } from "./types.ts";
+import type { I18n, ListStyle, TemplateArgs, Text, TextArg, TextError, TextList } from "./types.ts";
+/** `plugin.i18n.text`: a plain, frozen text value (no translation here). */
+export declare function text(source: string, args?: TemplateArgs): Text;
+/** `plugin.i18n.list`: a plain, frozen list value. */
+export declare function list(items: readonly TextArg[], style?: ListStyle): TextList;
+export declare const error: (source: string, args?: TemplateArgs) => TextError;
 export declare const i18n: (scope: ScopeImpl) => I18n;

package/dist/plugin/language.js

@@ -1,5 +1,79 @@
+/** `plugin.i18n`: the interface language of this run and text values (read-only). */
+import { Catalog, isTextValue, LIST_STYLES, loadPackageCatalog, renderText, textKey, textProblem, } from "../i18n.js";
+import { failure } from "./runtime.js";
+/** Copy arguments (arrays and objects only; texts are already frozen). */
+const copyArgs = (args) => Array.isArray(args) ? Object.freeze([...args]) : Object.freeze({ ...args });
+/** `plugin.i18n.text`: a plain, frozen text value (no translation here). */
+export function text(source, args) {
+    const value = { $vestraText: source };
+    if (args !== undefined && args !== null)
+        value.args = copyArgs(args);
+    const problem = textProblem(value);
+    if (problem)
+        throw failure("invalid", `text: ${problem}`);
+    return Object.freeze(value);
+}
+/** `plugin.i18n.list`: a plain, frozen list value. */
+export function list(items, style) {
+    if (!Array.isArray(items))
+        throw failure("invalid", "list: items is an array");
+    if (style !== undefined &&
+        !LIST_STYLES.includes(style))
+        throw failure("invalid", `list: style is one of ${LIST_STYLES.join(", ")}`);
+    const value = {
+        $vestraList: Object.freeze([
+            ...items,
+        ]),
+        ...(style === undefined ? {} : { style }),
+    };
+    const problem = textProblem(value);
+    if (problem)
+        throw failure("invalid", `list: ${problem}`);
+    return Object.freeze(value);
+}
+/** `plugin.i18n.error`: an Error whose message the player shows translated. */
+class TextErrorImpl extends Error {
+    text;
+    constructor(value) {
+        super(textKey(value));
+        this.name = "TextError";
+        this.text = value;
+    }
+}
+export const error = (source, args) => new TextErrorImpl(text(source, args));
+/** The plugin's catalog for this run's language, read once per runtime. */
+const catalogs = new WeakMap();
+function catalogOf(scope) {
+    const runtime = scope.runtime;
+    let catalog = catalogs.get(runtime);
+    if (!catalog) {
+        try {
+            catalog = loadPackageCatalog(runtime.directory, runtime.locale);
+        }
+        catch (error) {
+            // As the player: a broken catalog is reported and treated as missing.
+            console.error(`[${scope.id}] i18n: ${error.message}`);
+            catalog = new Catalog();
+        }
+        catalogs.set(runtime, catalog);
+    }
+    return catalog;
+}
 export const i18n = (scope) => Object.freeze({
     get locale() {
         return scope.runtime.locale;
     },
+    text,
+    list,
+    error,
+    resolve(value) {
+        if (typeof value === "string")
+            return catalogOf(scope).text(value);
+        const problem = isTextValue(value)
+            ? textProblem(value)
+            : "resolve takes a string or a text value";
+        if (problem)
+            throw failure("invalid", `resolve: ${problem}`);
+        return renderText(value, catalogOf(scope), scope.runtime.locale);
+    },
 });

package/dist/plugin/osd.d.ts

@@ -1,6 +1,14 @@
 import type { ScopeImpl } from "./scope.ts";
 import type { Osd } from "./types.ts";
-import type { TemplateArgsJson } from "../wire.ts";
-/** Copy and check template arguments: an array or object of ≤ 16 strings and numbers. */
+import type { TemplateArgsJson, TextValueJson } from "../wire.ts";
+/**
+ * Copy and check template arguments: an array or object of at most 16
+ * strings, finite numbers, texts and lists (`TEXT_LIMITS`).
+ */
 export declare function templateArgs(args: unknown): TemplateArgsJson | undefined;
+/**
+ * Check a shown text (`osd.show`, dialogs): source text, or a text value
+ * that carries its own arguments (then `args` is not given).
+ */
+export declare function shownText(text: unknown, args: unknown, what?: string): TextValueJson;
 export declare const osd: (scope: ScopeImpl) => Osd;

package/dist/plugin/osd.js

@@ -1,24 +1,38 @@
 /** On-screen display: a transient line and a persistent information block. */
 import { Latest } from "./runtime.js";
 import { failure } from "./runtime.js";
-/** Copy and check template arguments: an array or object of ≤ 16 strings and numbers. */
+import { isTextValue, textProblem } from "../i18n.js";
+/**
+ * Copy and check template arguments: an array or object of at most 16
+ * strings, finite numbers, texts and lists (`TEXT_LIMITS`).
+ */
 export function templateArgs(args) {
     if (args === undefined || args === null)
         return undefined;
-    const values = Array.isArray(args)
-        ? args
-        : typeof args === "object"
-            ? Object.values(args)
-            : null;
-    if (!values ||
-        values.length > 16 ||
-        values.some((value) => !((typeof value === "number" && Number.isFinite(value)) ||
-            typeof value === "string")))
-        throw failure("invalid", "args is an array or object of at most 16 strings and finite numbers");
+    const problem = textProblem(args, "args");
+    if (problem)
+        throw failure("invalid", problem);
     return Array.isArray(args)
         ? [...args]
         : { ...args };
 }
+/**
+ * Check a shown text (`osd.show`, dialogs): source text, or a text value
+ * that carries its own arguments (then `args` is not given).
+ */
+export function shownText(text, args, what = "text") {
+    if (typeof text === "string")
+        return text;
+    if (isTextValue(text)) {
+        const problem = textProblem(text);
+        if (problem)
+            throw failure("invalid", `${what}: ${problem}`);
+        if (args !== undefined && args !== null)
+            throw failure("invalid", `${what} is a text value: its args go inside it, not in args`);
+        return text;
+    }
+    throw failure("invalid", `${what} is a string or a text value`);
+}
 class PanelHandle {
     #scope;
     #pump;
@@ -30,19 +44,24 @@ class PanelHandle {
             throw new Error("a plugin can have only one osd panel");
         scope.runtime.services.set("osd.panel", this);
         this.#scope = scope;
-        this.#pump = new Latest(({ text, args }) => scope.runtime.host.osd.panel(text, args));
+        this.#pump = new Latest(({ text, args, maxColumns }) => scope.runtime.host.osd.panel(text, args, maxColumns));
         scope.add(this);
     }
-    set(text, args) {
+    set(text, args, options = {}) {
         if (this.#disposed)
             return;
         let value;
         try {
+            const max = options?.maxColumns;
+            if (max !== undefined &&
+                !(Number.isInteger(max) && max >= 8 && max <= 1000))
+                throw failure("invalid", "maxColumns is an integer from 8 to 1000");
             value = {
-                text,
-                ...(text === null || args === undefined
+                text: text === null ? null : shownText(text, args),
+                ...(text === null || args === undefined || args === null
                     ? {}
                     : { args: templateArgs(args) }),
+                ...(text === null || max === undefined ? {} : { maxColumns: max }),
             };
         }
         catch (error) {
@@ -67,6 +86,6 @@ class PanelHandle {
     }
 }
 export const osd = (scope) => ({
-    show: async (text, args) => scope.runtime.host.osd.show(text, templateArgs(args)),
+    show: async (text, args) => scope.runtime.host.osd.show(shownText(text, args), templateArgs(args)),
     panel: () => new PanelHandle(scope),
 });

package/dist/plugin/subtitles.js

@@ -1,5 +1,6 @@
 /** Subtitle selection, external SRT resources and this plugin's style layer. */
 import { createHash } from "node:crypto";
+import { isTextValue, textProblem } from "../i18n.js";
 import { Latest, failure, sleep, uncertain } from "./runtime.js";
 import { abortError } from "./player.js";
 const raws = new WeakMap();
@@ -226,7 +227,14 @@ export function subtitles(scope) {
             if (select !== "primary" && select !== "secondary" && select !== "none")
                 throw failure("invalid", 'select must be "primary", "secondary" or "none"');
             const title = options?.title;
-            if (title !== undefined &&
+            // A text value (`plugin.i18n.text`) is checked here and its shown
+            // length by the player.
+            if (isTextValue(title)) {
+                const problem = textProblem(title);
+                if (problem)
+                    throw failure("invalid", `title: ${problem}`);
+            }
+            else if (title !== undefined &&
                 (typeof title !== "string" ||
                     [...title].length < 1 ||
                     [...title].length > 200))