@camox/api-contract 0.43.0 → 0.45.0

package/dist/threads.js

@@ -0,0 +1,263 @@
+import { z } from "zod";
+
+//#region src/threads.ts
+/**
+* The kind of the transcript entry recording an editor's message, with its sender and the
+* operation id the studio sent it with as data (`editorMessageDataSchema`).
+*/
+const EDITOR_MESSAGE_ENTRY = "camox.editor-message";
+/** The kind of the transcript entry recording that an editor stopped a run, with them as data. */
+const RUN_STOPPED_ENTRY = "camox.run-stopped";
+/** Who sent a message in a thread. */
+const threadSenderSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	image: z.string().nullable()
+});
+/** Whether `data` names a sender. */
+const isSender = (data) => threadSenderSchema.safeParse(data).success;
+/** What an editor's message entry records: who sent it, and the operation id it was sent with. */
+const editorMessageDataSchema = threadSenderSchema.extend({ operationId: z.string().optional() });
+/**
+* A draft a Live thread started with its first write, becoming its thread, and the operation ids
+* of the messages of the run that made the write: the studio that sent one of them enters the
+* draft with the thread.
+*/
+const startedDraftSchema = z.object({
+	draftId: z.string(),
+	operationIds: z.array(z.string())
+});
+/** How a write touched what it names. */
+const touchKindSchema = z.enum([
+	"created",
+	"edited",
+	"moved",
+	"deleted",
+	"settings"
+]);
+/**
+* One thing a script's successful write touched, named so the studio can locate it: a Page (and
+* its Block, if any), a Synced Block's shared content, by its block definition, or a Layout (and
+* its Block, if any). `settings` is a Page's settings only (nickname, path, SEO, layout). `locale`
+* is the Locale the write was in, for a localized tool. Writes to Collection Records, Files and
+* Locales aren't on the Canvas, so they're left out.
+*/
+const touchBaseSchema = z.object({
+	kind: touchKindSchema,
+	locale: z.string().optional()
+});
+const touchSchema = z.discriminatedUnion("entity", [
+	touchBaseSchema.extend({
+		entity: z.literal("page"),
+		pageId: z.string(),
+		blockId: z.string().optional()
+	}),
+	touchBaseSchema.extend({
+		entity: z.literal("synced-block"),
+		/** The Synced Block's block definition id. */
+		blockType: z.string()
+	}),
+	touchBaseSchema.extend({
+		entity: z.literal("layout"),
+		layoutId: z.string(),
+		blockId: z.string().optional()
+	})
+]);
+/**
+* What one code-mode script's successful writes touched, in write order, and the operation ids
+* of the messages of the run it belongs to: only the studio that sent one of them follows it.
+*/
+const touchedBatchSchema = z.object({
+	operationIds: z.array(z.string()),
+	touches: z.array(touchSchema)
+});
+const EMPTY_THREAD_VIEW = {
+	messages: [],
+	running: false
+};
+const EMPTY_THREAD_STATE = {
+	steps: [],
+	running: false
+};
+/** Studio → thread. */
+const threadClientMessageSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("send"),
+		operationId: z.string().min(1),
+		text: z.string().min(1)
+	}),
+	z.object({ type: z.literal("stop") }),
+	z.object({ type: z.literal("resync") })
+]);
+/**
+* The code a thread closes its sockets with once it ended with its draft, and for good: it's
+* deleted, so reconnecting reaches nothing. A development draft, which stays open, gets a new
+* thread the next time the studio connects.
+*/
+const THREAD_ENDED_CLOSE_CODE = 4e3;
+const textOf = (content) => typeof content === "string" ? content : content.flatMap((part) => part.type === "text" ? [part.text] : []).join("").trim();
+/** What an assistant message is to the thread: a final answer, a tool round, or neither. */
+function assistantStep(id, message) {
+	if (message.content.some((part) => part.type === "toolCall")) return {
+		id,
+		type: "tools"
+	};
+	const text = message.stopReason === "stop" ? textOf(message.content) : "";
+	return text ? {
+		id,
+		type: "answer",
+		text
+	} : {
+		id,
+		type: "unfinished"
+	};
+}
+/** The sender an entry's data names, if any, without other fields it may carry. */
+function senderOf(data) {
+	if (!isSender(data)) return void 0;
+	const { id, name, image } = data;
+	return {
+		id,
+		name,
+		image
+	};
+}
+/** The step an entry is, if it's one the view depends on. */
+function threadStepOf(entry) {
+	const id = String(entry.id);
+	const sender = senderOf(entry.data);
+	if (entry.kind === "camox.run-stopped" && sender) return {
+		id,
+		type: "stopped",
+		sender
+	};
+	const message = entry.model?.find((candidate) => candidate.role !== "system");
+	if (!message) return void 0;
+	if (entry.kind === "camox.editor-message" && message.role === "user" && sender) return {
+		id,
+		type: "editor",
+		sender,
+		text: textOf(message.content)
+	};
+	if (message.role === "assistant") return assistantStep(id, message);
+	if (message.role === "toolResult") return {
+		id,
+		type: "tools"
+	};
+}
+/**
+* What the studio shows for a thread. A turn starts with an editor's message, and messages sent
+* while it runs join it. It ends with the agent's final message; text written beside tool calls
+* is never shown. A stopped turn shows who stopped it instead, and whatever its run wrote after
+* the stop is left out. A turn that ended without either shows a failed line in its place: its
+* run is over, or a later message started another run after its last model call came back
+* unfinished. While Pi retries a failed call, the run goes on, so the turn shows as working.
+*/
+function threadViewOf({ steps, running, ...drafts }) {
+	const messages = [];
+	let waiting;
+	let unfinished = false;
+	/** Ends the turn waiting for the agent's message, if any. */
+	const endTurn = () => {
+		waiting = void 0;
+		unfinished = false;
+	};
+	/** Ends the turn waiting for the agent's message with a failed line, if any. */
+	const fail = () => {
+		if (waiting !== void 0) messages.push({
+			id: `${waiting}:failed`,
+			from: "failed"
+		});
+		endTurn();
+	};
+	for (const step of steps) switch (step.type) {
+		case "editor":
+			if (unfinished) fail();
+			messages.push({
+				id: step.id,
+				from: "editor",
+				sender: step.sender,
+				text: step.text
+			});
+			waiting = step.id;
+			break;
+		case "stopped":
+			if (waiting === void 0) break;
+			messages.push({
+				id: step.id,
+				from: "stopped",
+				sender: step.sender
+			});
+			endTurn();
+			break;
+		case "answer":
+			if (waiting === void 0 && messages.at(-1)?.from === "stopped") break;
+			messages.push({
+				id: step.id,
+				from: "agent",
+				text: step.text
+			});
+			endTurn();
+			break;
+		case "tools":
+			unfinished = false;
+			break;
+		case "unfinished": unfinished = true;
+	}
+	if (!running) fail();
+	return {
+		...drafts,
+		messages,
+		running
+	};
+}
+const append = (state, entry) => {
+	const step = entry && threadStepOf(entry);
+	if (!step || state.steps.some((known) => known.id === step.id)) return state;
+	return {
+		...state,
+		steps: [...state.steps, step]
+	};
+};
+/** Folds one of Pi's agent events into the thread's state. */
+function reduceThreadState(state, event) {
+	switch (event.type) {
+		case "snapshot": return {
+			...state,
+			steps: event.entries.flatMap((entry) => threadStepOf(entry) ?? []),
+			running: event.run !== void 0
+		};
+		case "run_start": return {
+			...state,
+			running: true
+		};
+		case "run_end": return {
+			...state,
+			running: false
+		};
+		case "message_end":
+		case "entry_appended":
+		case "tool_execution_end": return append(state, event.entry);
+		default: return state;
+	}
+}
+/** Folds a batch of Pi's agent events into the thread's state. */
+const reduceThreadEvents = (state, events) => events.reduce(reduceThreadState, state);
+/** Folds what the thread sent over its socket into the thread's state. */
+function reduceThreadFrame(state, frame) {
+	switch (frame.type) {
+		case "events": return reduceThreadEvents(state, frame.events);
+		case "started-draft": return {
+			...state,
+			startedDraft: frame.startedDraft
+		};
+		case "continued-in": return {
+			...state,
+			continuedIn: frame.continuedIn
+		};
+		default: return state;
+	}
+}
+
+//#endregion
+export { EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, RUN_STOPPED_ENTRY, THREAD_ENDED_CLOSE_CODE, editorMessageDataSchema, isSender, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftSchema, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "license": "MIT",
   "files": [
     "src",
@@ -15,18 +15,70 @@
     "./query-keys": {
       "types": "./dist/query-keys.d.ts",
       "default": "./dist/query-keys.js"
+    },
+    "./ids": {
+      "types": "./dist/ids.d.ts",
+      "default": "./dist/ids.js"
+    },
+    "./drafts": {
+      "types": "./dist/drafts.d.ts",
+      "default": "./dist/drafts.js"
+    },
+    "./icon-catalog": {
+      "types": "./dist/icon-catalog.d.ts",
+      "default": "./dist/icon-catalog.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics.d.ts",
+      "default": "./dist/analytics.js"
+    },
+    "./threads": {
+      "types": "./dist/threads.d.ts",
+      "default": "./dist/threads.js"
+    },
+    "./projects": {
+      "types": "./dist/projects.d.ts",
+      "default": "./dist/projects.js"
     }
   },
+  "dependencies": {
+    "@iconify/types": "^2.0.0",
+    "@iconify/utils": "^3.1.7",
+    "zod": "^4.6.7"
+  },
   "devDependencies": {
-    "dts-bundle-generator": "^9.5.1",
-    "esbuild": "^0.25.12"
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-durable": "1.3.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-durable": "1.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-durable": {
+      "optional": true
+    }
   },
   "nx": {
     "tags": [
       "type:pkg"
-    ]
+    ],
+    "targets": {
+      "build": {
+        "inputs": [
+          "production",
+          "^production",
+          "{workspaceRoot}/apps/api/src/**/*",
+          "{workspaceRoot}/packages/ai-tools/src/**/*",
+          "!{workspaceRoot}/**/*.test.ts"
+        ]
+      }
+    }
   },
   "scripts": {
-    "build": "node build.mjs"
+    "build": "vp pack"
   }
 }

package/src/analytics.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+/**
+ * A GA4 measurement ID: `G-` followed by uppercase letters and digits. Shared so the dashboard
+ * checks an ID by the API's own rule before saving it.
+ */
+export const ga4MeasurementIdSchema = /* @__PURE__ */ z
+  .string()
+  .regex(/^G-[A-Z0-9]+$/, "Not a GA4 measurement ID");
+
+/**
+ * A PostHog project API key: `phc_` followed by letters and digits. The prefix tells it apart from
+ * a personal API key, which is secret and must never reach a public page.
+ */
+export const posthogProjectApiKeySchema = /* @__PURE__ */ z
+  .string()
+  .regex(/^phc_[A-Za-z0-9]+$/, "Not a PostHog project API key");
+
+/** The PostHog Cloud region a project lives in. */
+export const posthogRegionSchema = /* @__PURE__ */ z.enum(["us", "eu"]);
+
+export type PosthogRegion = z.output<typeof posthogRegionSchema>;

package/src/artifact.ts

@@ -0,0 +1,38 @@
+/**
+ * Artifact titles, shared by the SDK (frame titles, studio sidebar) and the API (Markdown
+ * Representation, write warnings), so every surface names an artifact the same way.
+ */
+
+export const UNTITLED_ARTIFACT = "Untitled artifact";
+
+const entities: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+};
+
+function decodeEntities(text: string) {
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, entity: string) => {
+    if (entity[0] !== "#") return entities[entity.toLowerCase()] ?? match;
+    const code =
+      entity[1] === "x" || entity[1] === "X"
+        ? Number.parseInt(entity.slice(2), 16)
+        : Number(entity.slice(1));
+    return Number.isNaN(code) ? match : String.fromCodePoint(code);
+  });
+}
+
+/** The non-empty `<title>` of an artifact source, if it has one. */
+export function artifactSourceTitle(source: string): string | undefined {
+  const match = /<title\b[^>]*>([\s\S]*?)<\/title\s*>/i.exec(source);
+  const title = match ? decodeEntities(match[1]).replace(/\s+/g, " ").trim() : "";
+  return title || undefined;
+}
+
+/** The artifact's name: its source's `<title>`, or "Untitled artifact". */
+export function artifactTitle(source: string): string {
+  return artifactSourceTitle(source) ?? UNTITLED_ARTIFACT;
+}

package/src/drafts.ts

@@ -0,0 +1,197 @@
+import type { Router } from "./index.ts";
+
+/** Request header naming the draft a request reads and writes (ADR 0011). Absent means Live. */
+export const DRAFT_HEADER = "x-camox-draft";
+
+/**
+ * Request header naming, by its tag, the locale a request reads and writes content in (ADR
+ * 0015). Absent means the project's default locale.
+ */
+export const LOCALE_HEADER = "x-camox-locale";
+
+/**
+ * Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
+ * exist yet. Its value is `"1"`.
+ */
+export const DRAFT_CREATE_HEADER = "x-camox-draft-create";
+
+/**
+ * The `x-camox-draft` value naming the caller's own development draft in the project a request
+ * acts on (ADR 0006, ADR 0011). Dev mode and the CLI always send it.
+ */
+export const DEVELOPMENT_DRAFT = "development";
+
+/**
+ * oRPC error code for a request naming the development draft before dev mode created it: the
+ * first dev-mode sync after login does, so the site has to run locally once first.
+ */
+export const NO_DEVELOPMENT_DRAFT_ERROR = "NO_DEVELOPMENT_DRAFT";
+
+/** URL search param carrying the current draft's id in the studio and the rendered site. */
+export const DRAFT_SEARCH_PARAM = "camox-draft";
+
+/** A regular draft is a named set of edits; a development draft backs a dev server. */
+export type DraftKind = "regular" | "development";
+
+/** How a regular draft ended. */
+export type DraftOutcome = "published" | "discarded";
+
+/** Who ended a draft, how and when, from its ended-drafts record (ADR 0009, ADR 0011). */
+export type EndedDraft = {
+  draftId: string;
+  outcome: DraftOutcome;
+  endedBy: { id: string; name: string };
+  endedAt: number;
+};
+
+/**
+ * The oRPC error code a request naming an ended draft fails with. Its `data` is an `EndedDraft`,
+ * so a page can render Live and say who published or discarded the draft.
+ */
+export const DRAFT_ENDED_ERROR_CODE = "DRAFT_ENDED";
+
+/**
+ * oRPC error code for a publish whose token no longer matches Live: Live changed since the
+ * preview, so nothing was applied and the caller reviews the new preview.
+ */
+export const CONFLICTS_CHANGED_ERROR = "CONFLICTS_CHANGED";
+
+/** oRPC error code for a publish refused because the draft still has blockers. */
+export const PUBLISH_BLOCKED_ERROR = "PUBLISH_BLOCKED";
+
+/**
+ * oRPC error code for a publish refused because the draft still has pending translations: every
+ * locale goes live together, unless the caller publishes anyway (ADR 0017).
+ */
+export const TRANSLATIONS_PENDING_ERROR = "TRANSLATIONS_PENDING";
+
+/**
+ * Why the publish tool published nothing of a draft with changes, and returned a fresh preview to
+ * review again, by the error code of each: Live changed since the preview, the draft has blockers,
+ * or translations are still running.
+ */
+export const NOT_PUBLISHED_CODES = {
+  conflictsChanged: CONFLICTS_CHANGED_ERROR,
+  blocked: PUBLISH_BLOCKED_ERROR,
+  translating: TRANSLATIONS_PENDING_ERROR,
+} as const;
+
+export type NotPublishedReason = keyof typeof NOT_PUBLISHED_CODES;
+
+/**
+ * Who Camox's own work is by: the creator of the drafts it opens to catch translations up, their
+ * publisher on Live, and who ended them. Shown as "Camox".
+ */
+export const CAMOX_ACTOR = "camox";
+
+/** The name Camox's own work shows under. */
+export const CAMOX_NAME = "Camox";
+
+/**
+ * oRPC error code for a content write that names no draft. Live is read-only (ADR 0003): content
+ * changes reach it only by publishing a draft, or through a release.
+ */
+export const LIVE_READ_ONLY_ERROR = "LIVE_READ_ONLY";
+
+// Whether each procedure of a router that follows drafts writes content. Live is read-only
+// (ADR 0003), so the API rejects a content write naming no draft, and the studio starts a draft
+// for one on Live. Every procedure is listed, so a new one fails the type check until it's
+// classified and can't be forgotten. Procedures that only fill a generated value (ADR 0012),
+// like `generateSummary`, write no content. A synced block's shared content is written through
+// `blocks` and `repeatableItems`. Releases and dev-mode sync aren't listed.
+const BLOCK_WRITES: Record<keyof Router["blocks"], boolean> = {
+  get: false,
+  getPageMarkdown: false,
+  getLayoutMarkdown: false,
+  getUsageCounts: false,
+  getPagesUsing: false,
+  getSyncedContent: false,
+  create: true,
+  updateContent: true,
+  updateSettings: true,
+  updatePosition: true,
+  delete: true,
+  deleteMany: true,
+  generateSummary: false,
+  duplicate: true,
+};
+
+const COLLECTION_WRITES: Record<keyof Router["collectionDefinitions"], boolean> = {
+  list: false,
+  get: false,
+  listRecords: false,
+  getRecord: false,
+  getRecordUsageCount: false,
+  findRecordsByField: false,
+  listRecordPageValues: false,
+  recordMarkdown: false,
+  createRecord: true,
+  editRecord: true,
+  deleteRecord: true,
+};
+
+// Uploads and replacements are content writes too, outside oRPC.
+const FILE_WRITES: Record<keyof Router["files"], boolean> = {
+  list: false,
+  get: false,
+  getUsageCount: false,
+  setAlt: true,
+  setFilename: true,
+  delete: true,
+  deleteMany: true,
+  // Switching AI metadata on or off changes content (ADR 0012); generating only fills it.
+  setAiMetadata: true,
+  generateMetadata: false,
+};
+
+const PAGE_WRITES: Record<keyof Router["pages"], boolean> = {
+  getByPath: false,
+  getStructure: false,
+  list: false,
+  listBySlug: false,
+  get: false,
+  create: true,
+  update: true,
+  delete: true,
+  // Switching AI SEO on or off changes content (ADR 0012), like writing either field.
+  setSeo: true,
+  setLayout: true,
+  generateSeo: false,
+};
+
+const ITEM_WRITES: Record<keyof Router["repeatableItems"], boolean> = {
+  get: false,
+  create: true,
+  updateContent: true,
+  updateSettings: true,
+  updatePosition: true,
+  duplicate: true,
+  generateSummary: false,
+  delete: true,
+};
+
+// Correcting the default locale's tag changes no content, so it needs no draft (ADR 0015).
+const LOCALE_WRITES: Record<keyof Router["locales"], boolean> = {
+  list: false,
+  add: true,
+  remove: true,
+  setDefaultTag: false,
+  listMissing: false,
+  addBack: true,
+};
+
+// `definitions` is absent: its sync is a release or a dev sync, never a studio content write.
+const CONTENT_WRITES: Partial<Record<keyof Router, Record<string, boolean>>> = {
+  blocks: BLOCK_WRITES,
+  locales: LOCALE_WRITES,
+  collectionDefinitions: COLLECTION_WRITES,
+  files: FILE_WRITES,
+  pages: PAGE_WRITES,
+  repeatableItems: ITEM_WRITES,
+};
+
+/** Whether the procedure at `path` (`[router, procedure]`) writes content. */
+export function isContentWrite(path: readonly string[]): boolean {
+  if (path.length !== 2) return false;
+  return CONTENT_WRITES[path[0] as keyof Router]?.[path[1]] === true;
+}

package/src/icon-catalog.ts

@@ -0,0 +1,60 @@
+import type { IconifyJSON } from "@iconify/types";
+import { getIconData, iconToSVG } from "@iconify/utils";
+
+import { ICON_CATALOG_VERSION, type IconSvgData } from "./icons.ts";
+
+// Kept out of the root entry so `@iconify/utils` never reaches client bundles.
+const collections = new Map<string, Promise<IconifyJSON>>();
+
+export async function loadIconCollection(prefix: string): Promise<IconifyJSON> {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(prefix)) throw new Error("Invalid icon collection");
+  const existing = collections.get(prefix);
+  if (existing) return existing;
+  const pending = (async () => {
+    const response = await fetch(
+      `https://unpkg.com/@iconify/json@${ICON_CATALOG_VERSION}/json/${prefix}.json`,
+      { signal: AbortSignal.timeout(30_000) },
+    );
+    if (!response.ok) throw new Error(`Unable to load icon collection ${prefix}`);
+    const data = (await response.json()) as IconifyJSON;
+    if (data.prefix !== prefix || !data.icons || !data.info?.license)
+      throw new Error("Invalid icon catalog or missing license");
+    return data;
+  })();
+  collections.set(prefix, pending);
+  // Bound worker memory; failed fetches must be retryable.
+  if (collections.size > 8) collections.delete(collections.keys().next().value!);
+  try {
+    return await pending;
+  } catch (error) {
+    collections.delete(prefix);
+    throw error;
+  }
+}
+
+export function iconCollectionIds(data: IconifyJSON): string[] {
+  return [...Object.keys(data.icons), ...Object.keys(data.aliases ?? {})]
+    .filter((name) => getIconData(data, name) !== null)
+    .sort()
+    .map((name) => `${data.prefix}:${name}`);
+}
+
+export function resolveIconSvg(data: IconifyJSON, id: string): IconSvgData {
+  const [prefix, name, extra] = id.split(":");
+  if (prefix !== data.prefix || !name || extra !== undefined) throw new Error("Invalid icon ID");
+  const icon = getIconData(data, name);
+  if (!icon) throw new Error(`Unknown icon: ${id}`);
+  const svg = iconToSVG(icon);
+  return {
+    body: svg.body,
+    attributes: svg.attributes,
+    attribution: data.info
+      ? {
+          collection: data.info.name,
+          author: data.info.author.name,
+          license: data.info.license.title,
+          url: data.info.license.url,
+        }
+      : undefined,
+  };
+}

package/src/icons.ts

@@ -0,0 +1,27 @@
+// One immutable snapshot for declarations, schemas, picker and SVG resolution.
+export const ICON_CATALOG_VERSION = "2.2.532";
+export type IconSvgData = {
+  body: string;
+  attributes: Record<string, string>;
+  attribution?: { collection: string; author: string; license: string; url?: string };
+};
+
+export function scopeIconSvgIds(body: string, prefix: string): string {
+  const ids = [...body.matchAll(/\sid="([^\s"]+)"/g)].map((match) => match[1]!);
+  if (!ids.length) return body;
+  const pattern = ids.map((id) => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+  return body.replace(
+    new RegExp(`([#;"])(${pattern})([")]|\\.[a-z])`, "g"),
+    (_match, before: string, id: string, after: string) => `${before}${prefix}${id}${after}`,
+  );
+}
+
+export function validateIconValue(
+  value: unknown,
+  schema: { fieldType?: string; enum?: unknown },
+): void {
+  if (schema.fieldType !== "Icon") return;
+  if (typeof value !== "string" || !Array.isArray(schema.enum) || !schema.enum.includes(value)) {
+    throw new Error(`Invalid icon ID: ${String(value)}`);
+  }
+}