@hyperdrive.bot/paseo-protocol 0.3.63 → 0.3.65

package/dist/tag-color.d.ts

@@ -0,0 +1,84 @@
+/**
+ * MARRA CUSTOMIZATION - per-tag colors.
+ *
+ * User tags live on `Agent.labels` as `tag:<name>=<value>` (see agent-labels
+ * conventions and packages/app/src/utils/agent-tags.ts). The VALUE was
+ * historically the literal string "true", and both existing readers - the app's
+ * `getAgentTags` and the server's `tagsFromLabels` - key off the label KEY and
+ * never interpret the value beyond the "false" tombstone.
+ *
+ * That makes the value a free storage slot: `tag:monumenta=teal` is already a
+ * legal, already-persisted, already-synced way to pin a tag's color, with no
+ * schema change, no migration and no new RPC. `agent-storage.ts` types labels as
+ * `z.record(z.string(), z.string())`, so there is nothing to widen.
+ *
+ * Resolution order, deliberately in that order:
+ *   1. An explicit, recognized color name in the label value wins.
+ *   2. Anything else (including the legacy "true", and any unrecognized name)
+ *      falls through to a stable hash of the tag name.
+ *
+ * Consequence worth stating: every session stored before this shipped lights up
+ * correctly on first render, because the color is a function of data we already
+ * have. Nothing backfills, nothing rewrites "true".
+ *
+ * This module is intentionally pure and pixel-free. It resolves a color NAME.
+ * Mapping a name to an actual hex or an ANSI code belongs to each surface (the
+ * app maps through its theme palette, the CLI can map to 256-color), so the
+ * protocol never carries UI colors and every surface still agrees on WHICH of
+ * the eight a given tag gets.
+ */
+/**
+ * The eight tag colors, in palette order. Eight is a deliberate ceiling: enough
+ * to encode a real taxonomy, few enough that a person still remembers what each
+ * one means by the end of the week.
+ *
+ * Order is part of the contract. Appending is safe; reordering or removing
+ * silently repaints every tag that hashes past the change, so do not.
+ */
+export declare const TAG_COLOR_NAMES: readonly ["red", "orange", "amber", "green", "teal", "blue", "purple", "pink"];
+export type TagColorName = (typeof TAG_COLOR_NAMES)[number];
+/**
+ * The label-key prefix that marks a user tag. `tag:monumenta` is the tag
+ * "monumenta". Lives here so the app and the protocol cannot drift; the server
+ * keeps its own copy in agent-list-filter.ts and is deliberately left alone in
+ * this change, since consolidating it is a separate refactor with its own blast
+ * radius.
+ */
+export declare const TAG_LABEL_PREFIX = "tag:";
+/** Whether `value` names one of the eight colors, case-insensitively. */
+export declare function isTagColorName(value: string | null | undefined): value is TagColorName;
+/**
+ * FNV-1a over the tag's UTF-16 code units, folded to a palette index.
+ *
+ * Chosen because it is tiny, dependency-free and identical in every runtime that
+ * can index a string, which is the whole point: iOS, desktop, web and the CLI
+ * must land on the same swatch for the same tag without coordinating. `>>> 0`
+ * keeps the accumulator unsigned after Math.imul, so the index is never negative.
+ */
+export declare function hashTagToColorIndex(tag: string): number;
+/**
+ * The color name for a tag, given the raw label value stored alongside it.
+ *
+ * `labelValue` is whatever `labels["tag:" + tag]` holds: a color name to pin it,
+ * "true" for the legacy default, or anything else. Unrecognized values are NOT
+ * an error - they fall through to the hash, which is what keeps this readable by
+ * a human editing ~/.paseo/agents/*.json by hand without being able to break the
+ * UI.
+ */
+export declare function resolveTagColorName(tag: string, labelValue?: string | null): TagColorName;
+/** One tag paired with the color it resolves to. */
+export interface ColoredTag {
+    tag: string;
+    color: TagColorName;
+}
+/**
+ * Every user tag on a label bag, with its resolved color, sorted by tag name.
+ *
+ * Sorted so a tab's stripe bands are stable across renders and across surfaces:
+ * an unsorted map iteration would let the same session paint its bands in a
+ * different order on desktop than on mobile.
+ */
+export declare function coloredTagsFromLabels(labels: Record<string, string> | null | undefined, tagPrefix?: string): ColoredTag[];
+/** Re-exported so callers can write the legacy value without hardcoding it. */
+export declare const TAG_LABEL_PRESENT_VALUE = "true";
+//# sourceMappingURL=tag-color.d.ts.map

package/dist/tag-color.js

@@ -0,0 +1,122 @@
+/**
+ * MARRA CUSTOMIZATION - per-tag colors.
+ *
+ * User tags live on `Agent.labels` as `tag:<name>=<value>` (see agent-labels
+ * conventions and packages/app/src/utils/agent-tags.ts). The VALUE was
+ * historically the literal string "true", and both existing readers - the app's
+ * `getAgentTags` and the server's `tagsFromLabels` - key off the label KEY and
+ * never interpret the value beyond the "false" tombstone.
+ *
+ * That makes the value a free storage slot: `tag:monumenta=teal` is already a
+ * legal, already-persisted, already-synced way to pin a tag's color, with no
+ * schema change, no migration and no new RPC. `agent-storage.ts` types labels as
+ * `z.record(z.string(), z.string())`, so there is nothing to widen.
+ *
+ * Resolution order, deliberately in that order:
+ *   1. An explicit, recognized color name in the label value wins.
+ *   2. Anything else (including the legacy "true", and any unrecognized name)
+ *      falls through to a stable hash of the tag name.
+ *
+ * Consequence worth stating: every session stored before this shipped lights up
+ * correctly on first render, because the color is a function of data we already
+ * have. Nothing backfills, nothing rewrites "true".
+ *
+ * This module is intentionally pure and pixel-free. It resolves a color NAME.
+ * Mapping a name to an actual hex or an ANSI code belongs to each surface (the
+ * app maps through its theme palette, the CLI can map to 256-color), so the
+ * protocol never carries UI colors and every surface still agrees on WHICH of
+ * the eight a given tag gets.
+ */
+/**
+ * The eight tag colors, in palette order. Eight is a deliberate ceiling: enough
+ * to encode a real taxonomy, few enough that a person still remembers what each
+ * one means by the end of the week.
+ *
+ * Order is part of the contract. Appending is safe; reordering or removing
+ * silently repaints every tag that hashes past the change, so do not.
+ */
+export const TAG_COLOR_NAMES = [
+    "red",
+    "orange",
+    "amber",
+    "green",
+    "teal",
+    "blue",
+    "purple",
+    "pink",
+];
+/**
+ * The label-key prefix that marks a user tag. `tag:monumenta` is the tag
+ * "monumenta". Lives here so the app and the protocol cannot drift; the server
+ * keeps its own copy in agent-list-filter.ts and is deliberately left alone in
+ * this change, since consolidating it is a separate refactor with its own blast
+ * radius.
+ */
+export const TAG_LABEL_PREFIX = "tag:";
+/** The label value that means "tagged, no explicit color" (the legacy default). */
+const LEGACY_PRESENT_VALUE = "true";
+/** The label value that tombstones a tag as absent. Mirrors `getAgentTags`. */
+const ABSENT_VALUE = "false";
+const TAG_COLOR_NAME_SET = new Set(TAG_COLOR_NAMES);
+/** Whether `value` names one of the eight colors, case-insensitively. */
+export function isTagColorName(value) {
+    return typeof value === "string" && TAG_COLOR_NAME_SET.has(value.trim().toLowerCase());
+}
+/**
+ * FNV-1a over the tag's UTF-16 code units, folded to a palette index.
+ *
+ * Chosen because it is tiny, dependency-free and identical in every runtime that
+ * can index a string, which is the whole point: iOS, desktop, web and the CLI
+ * must land on the same swatch for the same tag without coordinating. `>>> 0`
+ * keeps the accumulator unsigned after Math.imul, so the index is never negative.
+ */
+export function hashTagToColorIndex(tag) {
+    let hash = 0x811c9dc5;
+    const normalized = tag.trim().toLowerCase();
+    for (let i = 0; i < normalized.length; i += 1) {
+        hash ^= normalized.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash % TAG_COLOR_NAMES.length;
+}
+/**
+ * The color name for a tag, given the raw label value stored alongside it.
+ *
+ * `labelValue` is whatever `labels["tag:" + tag]` holds: a color name to pin it,
+ * "true" for the legacy default, or anything else. Unrecognized values are NOT
+ * an error - they fall through to the hash, which is what keeps this readable by
+ * a human editing ~/.paseo/agents/*.json by hand without being able to break the
+ * UI.
+ */
+export function resolveTagColorName(tag, labelValue) {
+    if (isTagColorName(labelValue)) {
+        return labelValue.trim().toLowerCase();
+    }
+    return TAG_COLOR_NAMES[hashTagToColorIndex(tag)];
+}
+/**
+ * Every user tag on a label bag, with its resolved color, sorted by tag name.
+ *
+ * Sorted so a tab's stripe bands are stable across renders and across surfaces:
+ * an unsorted map iteration would let the same session paint its bands in a
+ * different order on desktop than on mobile.
+ */
+export function coloredTagsFromLabels(labels, tagPrefix = TAG_LABEL_PREFIX) {
+    if (!labels)
+        return [];
+    const result = [];
+    for (const key of Object.keys(labels)) {
+        if (!key.startsWith(tagPrefix) || key.length <= tagPrefix.length)
+            continue;
+        const value = labels[key];
+        if (value === ABSENT_VALUE)
+            continue;
+        const tag = key.slice(tagPrefix.length);
+        result.push({ tag, color: resolveTagColorName(tag, value) });
+    }
+    result.sort((a, b) => a.tag.localeCompare(b.tag));
+    return result;
+}
+/** Re-exported so callers can write the legacy value without hardcoding it. */
+export const TAG_LABEL_PRESENT_VALUE = LEGACY_PRESENT_VALUE;
+//# sourceMappingURL=tag-color.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdrive.bot/paseo-protocol",
-  "version": "0.3.63",
+  "version": "0.3.65",
   "description": "Paseo shared protocol schemas and wire types",
   "files": [
     "dist",