@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/api/core/tags.ts

@@ -0,0 +1,911 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
+
+/**
+ * Tags — read and edit the tag catalog and its assignments.
+ *
+ * A **tag** is a colored label that lives in a **category**; a space carries at
+ * most one tag per category. This namespace is the catalog + assignment surface:
+ * the categories and tags themselves, which components carry which tags, and the
+ * assign/unassign operations. Tags attach to **Mass and Floor spaces only**.
+ *
+ * **Reserved sentinels.** The built-in **`DEPARTMENT`** category is owned by the
+ * program layer — it and the tags inside it are read-only here; create/update/
+ * delete reject it and direct you to {@linkcode PluginProgramApi}`.departments`.
+ * Every category also has a built-in **`DEFAULT`** tag that cannot be deleted;
+ * unassigning resets a component's category slot back to `DEFAULT` (a component
+ * is never left with a blank slot).
+ *
+ * Reads return plain records and never throw for a miss (`get*` return `null`,
+ * `list*` return `[]`). Ids are stable public strings.
+ *
+ * Sub-namespace members typed as optional (`?`) are **authored ahead of the
+ * host** — declared so plugins and codegen can see the shape, but kept out of the
+ * discovery manifest until the host lands them (at which point they are promoted
+ * to required `abstract` members).
+ *
+ * Accessed via `snaptrude.core.tags`.
+ */
+export abstract class PluginCoreTagsApi {
+  constructor() {}
+
+  /**
+   * List the tag categories.
+   *
+   * @returns A {@linkcode PluginCoreTagsListCategoriesResult} with a `categories`
+   *   array (empty when there are none), including the reserved `DEPARTMENT`
+   *   category.
+   *
+   * @examplePrompt List all the tag categories
+   * @examplePrompt What tag categories do I have?
+   * @examplePrompt Show every category and its tags
+   *
+   * # Example
+   * ```ts
+   * const { categories } = await snaptrude.core.tags.listCategories()
+   * for (const c of categories) console.log(c.name, c.tagIds.length)
+   * ```
+   */
+  public abstract listCategories(): PluginApiReturn<PluginCoreTagsListCategoriesResult>
+
+  /**
+   * Get a single tag category by id.
+   *
+   * @param categoryId - The id of the category to read.
+   * @returns The matching {@linkcode PluginCoreTagCategory}, or `null` if no
+   *   category has that id.
+   *
+   * @examplePrompt Get the tag category with id cat_3
+   * @examplePrompt Look up a category by its id
+   * @examplePrompt Which tags are in this category?
+   *
+   * # Example
+   * ```ts
+   * const category = await snaptrude.core.tags.getCategory("cat_3")
+   * if (category) console.log(category.name, category.tagIds)
+   * ```
+   */
+  public abstract getCategory(
+    categoryId: string,
+  ): PluginApiReturn<PluginCoreTagsGetCategoryResult>
+
+  /**
+   * List tags, optionally within one category.
+   *
+   * @param categoryId - Optional category filter; omit to list every tag.
+   * @returns A {@linkcode PluginCoreTagsListResult} with a `tags` array (empty
+   *   when there are none).
+   *
+   * @examplePrompt List every tag in the project
+   * @examplePrompt Show the tags in category cat_3
+   * @examplePrompt What tags are available?
+   *
+   * # Example
+   * ```ts
+   * const { tags } = await snaptrude.core.tags.list("cat_3")
+   * for (const t of tags) console.log(t.name, t.color)
+   * ```
+   */
+  public abstract list(
+    categoryId?: string,
+  ): PluginApiReturn<PluginCoreTagsListResult>
+
+  /**
+   * Get a single tag by id.
+   *
+   * @param tagId - The id of the tag to read.
+   * @returns The matching {@linkcode PluginCoreTag}, or `null` if no tag has that
+   *   id.
+   *
+   * @examplePrompt Get the tag with id tag_9
+   * @examplePrompt Look up a single tag by its id
+   * @examplePrompt What color is this tag?
+   *
+   * # Example
+   * ```ts
+   * const tag = await snaptrude.core.tags.get("tag_9")
+   * if (tag) console.log(tag.name, tag.color)
+   * ```
+   */
+  public abstract get(
+    tagId: string,
+  ): PluginApiReturn<PluginCoreTagsGetResult>
+
+  /**
+   * List the tags carried by a component.
+   *
+   * Returns one entry per category the component is tagged in, each carrying the
+   * category and tag names and the tag color.
+   *
+   * @param componentId - The `Component.id` to read.
+   * @returns A {@linkcode PluginCoreTagsGetTagsForComponentResult} with a `tags`
+   *   array (empty when the component has none or does not exist).
+   *
+   * @examplePrompt What tags does this space have?
+   * @examplePrompt List the tags on component cmp_42
+   * @examplePrompt Show the labels applied to this room
+   *
+   * # Example
+   * ```ts
+   * const { tags } = await snaptrude.core.tags.getTagsForComponent("cmp_42")
+   * for (const t of tags) console.log(t.categoryName, t.tagName)
+   * ```
+   *
+   * @deprecated Use `core.tags.listForComponent`
+   */
+  public abstract getTagsForComponent(
+    componentId: ComponentHandle,
+  ): PluginApiReturn<PluginCoreTagsGetTagsForComponentResult>
+
+  /**
+   * List the tags carried by a component.
+   *
+   * Returns one entry per category the component is tagged in, each carrying the
+   * category and tag names and the tag color. Canonical home of the read formerly
+   * at `getTagsForComponent` (now deprecated).
+   *
+   * @param componentId - The `Component.id` to read.
+   * @returns A {@linkcode PluginCoreTagsGetTagsForComponentResult} with a `tags`
+   *   array (empty when the component has none or does not exist).
+   *
+   * @examplePrompt What tags does this space have?
+   * @examplePrompt List the tags on component cmp_42
+   * @examplePrompt Show the labels applied to this room
+   *
+   * # Example
+   * ```ts
+   * const { tags } = await snaptrude.core.tags.listForComponent("cmp_42")
+   * for (const t of tags) console.log(t.categoryName, t.tagName)
+   * ```
+   */
+  public abstract listForComponent(
+    componentId: ComponentHandle,
+  ): PluginApiReturn<PluginCoreTagsGetTagsForComponentResult>
+
+  /**
+   * List the tags carried by many components in one call.
+   *
+   * The plural of {@linkcode PluginCoreTagsApi.listForComponent}: pass
+   * `componentIds` to read specific components (unknown ids are skipped), or
+   * omit it to read **every** taggable component (Mass/Floor space) in the
+   * project. Each entry carries the component id and its tags — one per tagged
+   * category, with the tag's `color` — so a plugin can color every space by a
+   * chosen category's tag in a single round-trip.
+   *
+   * @param componentIds - Optional `Component.id`s to read; omit for all spaces.
+   * @returns A {@linkcode PluginCoreTagsListForComponentsResult} with a
+   *   `components` array, one entry per component (in input order when
+   *   `componentIds` is given).
+   *
+   * @performance One round-trip for any number of components — use this instead of a `listForComponent` loop.
+   *
+   * @examplePrompt Get the tags of every space with their colors
+   * @examplePrompt List the tags on all rooms so I can color them by Occupancy
+   * @examplePrompt Which tag does each selected space carry?
+   *
+   * # Example
+   * ```ts
+   * const { components } = await snaptrude.core.tags.listForComponents()
+   * for (const c of components) {
+   *   const occupancy = c.tags.find((t) => t.categoryName === "Occupancy")
+   *   if (occupancy) paint(c.componentId, occupancy.color)
+   * }
+   * ```
+   */
+  public abstract listForComponents(
+    componentIds?: ComponentHandle[],
+  ): PluginApiReturn<PluginCoreTagsListForComponentsResult>
+
+  /**
+   * List the components carrying a given tag or category.
+   *
+   * Provide **exactly one** of `tagId` (components with that specific tag) or
+   * `categoryId` (components carrying any non-default tag in that category). With
+   * `categoryId`, pass `untagged: true` to instead return the components that have
+   * **no** non-default tag in that category. `untagged` is valid only alongside
+   * `categoryId`.
+   *
+   * @param filter - A {@linkcode PluginCoreTagsListComponentsArgs} filter with
+   *   exactly one of `tagId`, `categoryId`, plus optional `untagged` (with
+   *   `categoryId`).
+   * @returns A {@linkcode PluginCoreTagsListComponentsResult} with a
+   *   `componentIds` array (empty when none match).
+   *
+   * @examplePrompt Which spaces have the tag tag_9?
+   * @examplePrompt List every component tagged in category cat_3
+   * @examplePrompt Which spaces are untagged in the Occupancy category?
+   *
+   * # Example
+   * ```ts
+   * const { componentIds } = await snaptrude.core.tags.listComponents({ tagId: "tag_9" })
+   * console.log(`${componentIds.length} components`)
+   * ```
+   */
+  public abstract listComponents(
+    filter: { tagId?: string; categoryId?: string; untagged?: boolean },
+  ): PluginApiReturn<PluginCoreTagsListComponentsResult>
+
+  /**
+   * Create a new tag category.
+   *
+   * @param name - Display name of the new category.
+   * @returns The new {@linkcode PluginCoreTagCategory}.
+   * @throws If the name collides with the reserved `DEPARTMENT` category, or the
+   *   category could not be created.
+   *
+   * @examplePrompt Create a tag category called Fire Rating
+   * @examplePrompt Add a new category named Zone
+   * @examplePrompt Make a category for occupancy type
+   *
+   * # Example
+   * ```ts
+   * const category = await snaptrude.core.tags.createCategory("Fire Rating")
+   * ```
+   */
+  public abstract createCategory(
+    name: string,
+  ): PluginApiReturn<PluginCoreTagsCreateCategoryResult>
+
+  /**
+   * Rename a tag category.
+   *
+   * @param categoryId - The id of the category to rename.
+   * @param name - The category's new display name.
+   * @returns The updated {@linkcode PluginCoreTagCategory}.
+   * @throws If no category has the given id, or it is the reserved `DEPARTMENT`
+   *   category.
+   *
+   * @examplePrompt Rename category cat_3 to Occupancy
+   * @examplePrompt Change the name of this tag category
+   * @examplePrompt Update the Zone category's name
+   *
+   * # Example
+   * ```ts
+   * const category = await snaptrude.core.tags.updateCategory("cat_3", "Occupancy")
+   * ```
+   */
+  public abstract updateCategory(
+    categoryId: string,
+    name: string,
+  ): PluginApiReturn<PluginCoreTagsUpdateCategoryResult>
+
+  /**
+   * Delete a tag category and all its tags.
+   *
+   * **Non-undoable.** Every component tagged in this category is reset to the
+   * category's `DEFAULT`; the result reports how many tags were removed and how
+   * many components were reset.
+   *
+   * @param categoryId - The id of the category to delete.
+   * @returns The impact counts (`deletedTagCount`, `resetComponentCount`).
+   * @throws If no category has the given id, or it is the reserved `DEPARTMENT`
+   *   category.
+   *
+   * @examplePrompt Delete the Zone tag category
+   * @examplePrompt Remove category cat_3 and all its tags
+   * @examplePrompt Delete this category
+   *
+   * # Example
+   * ```ts
+   * const { deletedTagCount } = await snaptrude.core.tags.deleteCategory("cat_3")
+   * ```
+   */
+  public abstract deleteCategory(
+    categoryId: string,
+  ): PluginApiReturn<PluginCoreTagsDeleteCategoryResult>
+
+  /**
+   * Create a new tag in a category.
+   *
+   * @param categoryId - The category the new tag belongs to.
+   * @param name - Display name of the new tag.
+   * @param color - Optional CSS hex color string (auto-assigned if omitted).
+   * @returns The new {@linkcode PluginCoreTag}.
+   * @throws If no category has the given id, or it is the reserved `DEPARTMENT`
+   *   category.
+   *
+   * @examplePrompt Add a tag called 2-hour to the Fire Rating category
+   * @examplePrompt Create a red High Priority tag in category cat_3
+   * @examplePrompt Make a new tag named Retail
+   *
+   * # Example
+   * ```ts
+   * const tag = await snaptrude.core.tags.create("cat_3", "Retail", "#b5e1dc")
+   * ```
+   */
+  public abstract create(
+    categoryId: string,
+    name: string,
+    color?: string,
+  ): PluginApiReturn<PluginCoreTagsCreateResult>
+
+  /**
+   * Update a tag's name and/or color.
+   *
+   * A **sparse** update: omitted fields are left unchanged.
+   *
+   * @param tagId - The id of the tag to update.
+   * @param options - Any of `name`, `color`; omitted fields are left unchanged.
+   * @returns The updated {@linkcode PluginCoreTag}.
+   * @throws If no tag has the given id, or it belongs to the reserved
+   *   `DEPARTMENT` category.
+   *
+   * @examplePrompt Rename tag tag_9 to Retail
+   * @examplePrompt Change this tag's color to #ff8800
+   * @examplePrompt Recolor the High Priority tag
+   *
+   * # Example
+   * ```ts
+   * const tag = await snaptrude.core.tags.update("tag_9", { name: "Retail" })
+   * ```
+   */
+  public abstract update(
+    tagId: string,
+    options?: { name?: string; color?: string },
+  ): PluginApiReturn<PluginCoreTagsUpdateResult>
+
+  /**
+   * Delete a tag.
+   *
+   * **Non-undoable.** Every component carrying this tag is reset to its
+   * category's `DEFAULT`; the result reports how many components were reset. The
+   * built-in `DEFAULT` tag of a category cannot be deleted.
+   *
+   * @param tagId - The id of the tag to delete.
+   * @returns The impact count (`resetComponentCount`).
+   * @throws If no tag has the given id, it is a `DEFAULT` tag, or it belongs to
+   *   the reserved `DEPARTMENT` category.
+   *
+   * @examplePrompt Delete the Retail tag
+   * @examplePrompt Remove tag tag_9
+   * @examplePrompt Delete this label
+   *
+   * # Example
+   * ```ts
+   * const { resetComponentCount } = await snaptrude.core.tags.delete("tag_9")
+   * ```
+   */
+  public abstract delete(
+    tagId: string,
+  ): PluginApiReturn<PluginCoreTagsDeleteResult>
+
+  /**
+   * Assign a tag to components, creating the category and tag if needed.
+   *
+   * Resolves `tagName` within the category named `categoryName`: if the category
+   * or the tag does not exist yet it is created, otherwise the existing one is
+   * reused. The resolved tag is then applied to each taggable component (Mass/Floor
+   * spaces) — resolve-or-create and assign are **one atomic, undoable action**.
+   * Because a component carries one tag per category, this replaces any existing
+   * tag from that category. Components that are locked, not taggable, or not found
+   * are returned in `skipped` with a reason — never silently dropped. Rejects the
+   * reserved `DEPARTMENT` category.
+   *
+   * @param componentIds - The components to tag (at least one).
+   * @param categoryName - The tag category; created if it does not exist (not
+   *   `DEPARTMENT`).
+   * @param tagName - The tag within the category; created if it does not exist,
+   *   else reused.
+   * @returns A {@linkcode PluginCoreTagsAssignResult} — the resolved
+   *   `categoryId`/`tagId`, whether each was created, and the `assigned`/`skipped`
+   *   split.
+   * @throws If `categoryName` is the reserved `DEPARTMENT` category.
+   *
+   * @examplePrompt Tag the selected spaces as Retail in the Zone category
+   * @examplePrompt Tag these rooms High Priority, creating the tag if it doesn't exist
+   * @examplePrompt Put cmp_1 and cmp_2 in Zone / Retail
+   *
+   * # Example
+   * ```ts
+   * const { tagId, tagCreated, assigned } = await snaptrude.core.tags.assign(
+   *   ["cmp_1", "cmp_2"],
+   *   "Zone",
+   *   "Retail",
+   * )
+   * ```
+   */
+  public abstract assign(
+    componentIds: ComponentHandle[],
+    categoryName: string,
+    tagName: string,
+  ): PluginApiReturn<PluginCoreTagsAssignResult>
+
+  /**
+   * Clear a category's tag from components.
+   *
+   * Resets each component's slot for the given category back to `DEFAULT` (a
+   * component always has a `DEFAULT` — the field is never blanked). Components
+   * that are locked, not taggable, or not found are returned in `skipped`.
+   *
+   * @param categoryId - The category slot to reset to default.
+   * @param componentIds - The components to clear (at least one).
+   * @returns A {@linkcode PluginCoreAssignOutcome} splitting `assigned` (reset to
+   *   default) from `skipped`.
+   * @throws If no category has the given id.
+   *
+   * @examplePrompt Remove the Occupancy tag from the selected spaces
+   * @examplePrompt Clear category cat_3 on components cmp_1 and cmp_2
+   * @examplePrompt Untag these rooms in the Zone category
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.tags.unassign("cat_3", ["cmp_1", "cmp_2"])
+   * ```
+   */
+  public abstract unassign(
+    categoryId: string,
+    componentIds: ComponentHandle[],
+  ): PluginApiReturn<PluginCoreTagsUnassignResult>
+}
+
+/**
+ * A tag category — a named slot that holds a set of mutually-exclusive tags.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public category id |
+ * | `name` | `string` | Display name |
+ * | `tagIds` | `string[]` | Ids of the tags in this category |
+ */
+export const PluginCoreTagCategory = z.object({
+  id: z.string(),
+  name: z.string(),
+  tagIds: z.array(z.string()),
+})
+export type PluginCoreTagCategory = z.infer<typeof PluginCoreTagCategory>
+
+/**
+ * A tag — a colored label within a category.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public tag id |
+ * | `categoryId` | `string` | The id of the category this tag belongs to |
+ * | `name` | `string` | Display name |
+ * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
+ */
+export const PluginCoreTag = z.object({
+  id: z.string(),
+  categoryId: z.string(),
+  name: z.string(),
+  color: z.string(),
+})
+export type PluginCoreTag = z.infer<typeof PluginCoreTag>
+
+/**
+ * A tag as carried by a component — the category and tag names resolved for
+ * display.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The category's id |
+ * | `categoryName` | `string` | The category's display name |
+ * | `tagId` | `string` | The tag's id |
+ * | `tagName` | `string` | The tag's display name |
+ * | `color` | `string` | The tag's CSS hex color string |
+ */
+export const PluginCoreComponentTag = z.object({
+  categoryId: z.string(),
+  categoryName: z.string(),
+  tagId: z.string(),
+  tagName: z.string(),
+  color: z.string(),
+})
+export type PluginCoreComponentTag = z.infer<typeof PluginCoreComponentTag>
+
+/**
+ * The outcome of an assign/unassign — which components changed and which were
+ * skipped (with a reason).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `assigned` | `string[]` | Ids of the components that were changed |
+ * | `skipped` | `{ id: string; reason: "locked" \| "not-taggable" \| "not-found" }[]` | Components that were not changed, each with a reason |
+ */
+export const PluginCoreAssignOutcome = z.object({
+  assigned: z.array(z.string()),
+  skipped: z.array(
+    z.object({
+      id: z.string(),
+      reason: z.enum(["locked", "not-taggable", "not-found"]),
+    }),
+  ),
+})
+export type PluginCoreAssignOutcome = z.infer<typeof PluginCoreAssignOutcome>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.listCategories}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categories` | {@linkcode PluginCoreTagCategory}`[]` | Every tag category (including the reserved `DEPARTMENT`) |
+ */
+export const PluginCoreTagsListCategoriesResult = z.object({
+  categories: z.array(PluginCoreTagCategory),
+})
+export type PluginCoreTagsListCategoriesResult = z.infer<
+  typeof PluginCoreTagsListCategoriesResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.getCategory}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The id of the category to read |
+ */
+export const PluginCoreTagsGetCategoryArgs = z.object({
+  categoryId: z.string(),
+})
+export type PluginCoreTagsGetCategoryArgs = z.infer<
+  typeof PluginCoreTagsGetCategoryArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.getCategory} — the category, or `null`
+ * when no category has the given id.
+ */
+export const PluginCoreTagsGetCategoryResult = PluginCoreTagCategory.nullable()
+export type PluginCoreTagsGetCategoryResult = z.infer<
+  typeof PluginCoreTagsGetCategoryResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string \| undefined` | Optional category filter; omit to list every tag |
+ */
+export const PluginCoreTagsListArgs = z.object({
+  categoryId: z.string().optional(),
+})
+export type PluginCoreTagsListArgs = z.infer<typeof PluginCoreTagsListArgs>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tags` | {@linkcode PluginCoreTag}`[]` | The matching tags (empty when none) |
+ */
+export const PluginCoreTagsListResult = z.object({
+  tags: z.array(PluginCoreTag),
+})
+export type PluginCoreTagsListResult = z.infer<typeof PluginCoreTagsListResult>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagId` | `string` | The id of the tag to read |
+ */
+export const PluginCoreTagsGetArgs = z.object({
+  tagId: z.string(),
+})
+export type PluginCoreTagsGetArgs = z.infer<typeof PluginCoreTagsGetArgs>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.get} — the tag, or `null` when no tag
+ * has the given id.
+ */
+export const PluginCoreTagsGetResult = PluginCoreTag.nullable()
+export type PluginCoreTagsGetResult = z.infer<typeof PluginCoreTagsGetResult>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.getTagsForComponent}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentId` | `ComponentHandle` | The `Component.id` to read |
+ */
+export const PluginCoreTagsGetTagsForComponentArgs = z.object({
+  componentId: ComponentHandle,
+})
+export type PluginCoreTagsGetTagsForComponentArgs = z.infer<
+  typeof PluginCoreTagsGetTagsForComponentArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.getTagsForComponent}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tags` | {@linkcode PluginCoreComponentTag}`[]` | The component's tags, one per tagged category (empty when none) |
+ */
+export const PluginCoreTagsGetTagsForComponentResult = z.object({
+  tags: z.array(PluginCoreComponentTag),
+})
+export type PluginCoreTagsGetTagsForComponentResult = z.infer<
+  typeof PluginCoreTagsGetTagsForComponentResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]?` | Components to read; omit for every taggable component |
+ */
+export const PluginCoreTagsListForComponentsArgs = z.object({
+  componentIds: z.array(ComponentHandle).optional(),
+})
+export type PluginCoreTagsListForComponentsArgs = z.infer<
+  typeof PluginCoreTagsListForComponentsArgs
+>
+
+/**
+ * One component's tags, for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentId` | `ComponentHandle` | The component's id |
+ * | `tags` | {@linkcode PluginCoreComponentTag}`[]` | Its tags, one per tagged category (empty when none) |
+ */
+export const PluginCoreComponentTags = z.object({
+  componentId: ComponentHandle,
+  tags: z.array(PluginCoreComponentTag),
+})
+export type PluginCoreComponentTags = z.infer<typeof PluginCoreComponentTags>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode PluginCoreComponentTags}`[]` | One entry per component |
+ */
+export const PluginCoreTagsListForComponentsResult = z.object({
+  components: z.array(PluginCoreComponentTags),
+})
+export type PluginCoreTagsListForComponentsResult = z.infer<
+  typeof PluginCoreTagsListForComponentsResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.listComponents}. Provide exactly one
+ * of `tagId`, `categoryId`. `untagged` is valid only with `categoryId`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagId` | `string \| undefined` | Components carrying this specific tag |
+ * | `categoryId` | `string \| undefined` | Components carrying any non-default tag in this category |
+ * | `untagged` | `boolean \| undefined` | With `categoryId`, return components with **no** non-default tag in that category instead |
+ */
+export const PluginCoreTagsListComponentsArgs = z
+  .object({
+    tagId: z.string().optional(),
+    categoryId: z.string().optional(),
+    untagged: z.boolean().optional(),
+  })
+  .refine((v) => (v.tagId == null) !== (v.categoryId == null), {
+    message: "Provide exactly one of tagId or categoryId",
+  })
+  .refine((v) => v.untagged == null || v.categoryId != null, {
+    message: "untagged is valid only together with categoryId",
+  })
+export type PluginCoreTagsListComponentsArgs = z.infer<
+  typeof PluginCoreTagsListComponentsArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.listComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]` | Ids of the matching components (empty when none) |
+ */
+export const PluginCoreTagsListComponentsResult = z.object({
+  componentIds: z.array(ComponentHandle),
+})
+export type PluginCoreTagsListComponentsResult = z.infer<
+  typeof PluginCoreTagsListComponentsResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.createCategory}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the new category |
+ */
+export const PluginCoreTagsCreateCategoryArgs = z.object({
+  name: z.string(),
+})
+export type PluginCoreTagsCreateCategoryArgs = z.infer<
+  typeof PluginCoreTagsCreateCategoryArgs
+>
+
+/** Result of {@linkcode PluginCoreTagsApi.createCategory} — the new category. */
+export const PluginCoreTagsCreateCategoryResult = PluginCoreTagCategory
+export type PluginCoreTagsCreateCategoryResult = z.infer<
+  typeof PluginCoreTagsCreateCategoryResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.updateCategory}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The id of the category to rename |
+ * | `name` | `string` | The category's new display name |
+ */
+export const PluginCoreTagsUpdateCategoryArgs = z.object({
+  categoryId: z.string(),
+  name: z.string(),
+})
+export type PluginCoreTagsUpdateCategoryArgs = z.infer<
+  typeof PluginCoreTagsUpdateCategoryArgs
+>
+
+/** Result of {@linkcode PluginCoreTagsApi.updateCategory} — the updated category. */
+export const PluginCoreTagsUpdateCategoryResult = PluginCoreTagCategory
+export type PluginCoreTagsUpdateCategoryResult = z.infer<
+  typeof PluginCoreTagsUpdateCategoryResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.deleteCategory}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The id of the category to delete |
+ */
+export const PluginCoreTagsDeleteCategoryArgs = z.object({
+  categoryId: z.string(),
+})
+export type PluginCoreTagsDeleteCategoryArgs = z.infer<
+  typeof PluginCoreTagsDeleteCategoryArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.deleteCategory} — the impact of the
+ * (non-undoable) delete.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `deletedTagCount` | `number` | Number of tags removed with the category |
+ * | `resetComponentCount` | `number` | Number of components reset to their default |
+ */
+export const PluginCoreTagsDeleteCategoryResult = z.object({
+  deletedTagCount: z.number().int(),
+  resetComponentCount: z.number().int(),
+})
+export type PluginCoreTagsDeleteCategoryResult = z.infer<
+  typeof PluginCoreTagsDeleteCategoryResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The category the new tag belongs to |
+ * | `name` | `string` | Display name of the new tag |
+ * | `color` | `string \| undefined` | CSS hex color string (auto-assigned if omitted) |
+ */
+export const PluginCoreTagsCreateArgs = z.object({
+  categoryId: z.string(),
+  name: z.string(),
+  color: z.string().optional(),
+})
+export type PluginCoreTagsCreateArgs = z.infer<typeof PluginCoreTagsCreateArgs>
+
+/** Result of {@linkcode PluginCoreTagsApi.create} — the new tag. */
+export const PluginCoreTagsCreateResult = PluginCoreTag
+export type PluginCoreTagsCreateResult = z.infer<
+  typeof PluginCoreTagsCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.update}. Sparse — only the provided
+ * fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagId` | `string` | The id of the tag to update |
+ * | `name` | `string \| undefined` | New display name (unchanged if omitted) |
+ * | `color` | `string \| undefined` | New CSS hex color (unchanged if omitted) |
+ */
+export const PluginCoreTagsUpdateArgs = z.object({
+  tagId: z.string(),
+  name: z.string().optional(),
+  color: z.string().optional(),
+})
+export type PluginCoreTagsUpdateArgs = z.infer<typeof PluginCoreTagsUpdateArgs>
+
+/** Result of {@linkcode PluginCoreTagsApi.update} — the updated tag. */
+export const PluginCoreTagsUpdateResult = PluginCoreTag
+export type PluginCoreTagsUpdateResult = z.infer<
+  typeof PluginCoreTagsUpdateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagId` | `string` | The id of the tag to delete |
+ */
+export const PluginCoreTagsDeleteArgs = z.object({
+  tagId: z.string(),
+})
+export type PluginCoreTagsDeleteArgs = z.infer<typeof PluginCoreTagsDeleteArgs>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.delete} — the impact of the
+ * (non-undoable) delete.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `resetComponentCount` | `number` | Number of components reset to their category default |
+ */
+export const PluginCoreTagsDeleteResult = z.object({
+  resetComponentCount: z.number().int(),
+})
+export type PluginCoreTagsDeleteResult = z.infer<
+  typeof PluginCoreTagsDeleteResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.assign}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]` | The components to tag (at least one) |
+ * | `categoryName` | `string` | The tag category; created if it does not exist (not `DEPARTMENT`) |
+ * | `tagName` | `string` | The tag within the category; created if it does not exist, else reused |
+ */
+export const PluginCoreTagsAssignArgs = z.object({
+  componentIds: z.array(ComponentHandle).min(1),
+  categoryName: z.string(),
+  tagName: z.string(),
+})
+export type PluginCoreTagsAssignArgs = z.infer<typeof PluginCoreTagsAssignArgs>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.assign} — the resolved category/tag, what
+ * was created, and the assign outcome.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | Id of the resolved (or newly created) category |
+ * | `tagId` | `string` | Id of the resolved (or newly created) tag |
+ * | `categoryCreated` | `boolean` | Whether the category was created by this call |
+ * | `tagCreated` | `boolean` | Whether the tag was created by this call |
+ * | `assigned` | `string[]` | Ids of the components that were tagged |
+ * | `skipped` | `{ id: string; reason: "locked" \| "not-taggable" \| "not-found" }[]` | Components not tagged, each with a reason |
+ */
+export const PluginCoreTagsAssignResult = PluginCoreAssignOutcome.extend({
+  categoryId: z.string(),
+  tagId: z.string(),
+  categoryCreated: z.boolean(),
+  tagCreated: z.boolean(),
+})
+export type PluginCoreTagsAssignResult = z.infer<
+  typeof PluginCoreTagsAssignResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.unassign}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The category slot to reset to default |
+ * | `componentIds` | `ComponentHandle[]` | The components to clear (at least one) |
+ */
+export const PluginCoreTagsUnassignArgs = z.object({
+  categoryId: z.string(),
+  componentIds: z.array(ComponentHandle).min(1),
+})
+export type PluginCoreTagsUnassignArgs = z.infer<
+  typeof PluginCoreTagsUnassignArgs
+>
+
+/** Result of {@linkcode PluginCoreTagsApi.unassign} — the unassign outcome. */
+export const PluginCoreTagsUnassignResult = PluginCoreAssignOutcome
+export type PluginCoreTagsUnassignResult = z.infer<
+  typeof PluginCoreTagsUnassignResult
+>