dsh-agent-crew-faces 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tushar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,37 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/experimental/crew-faces/README.md
+/:
+  en: 43ce1f2d12a7b7d0
+  zh: ab9097841f16ba51
+/deepseek-ai-dsh-crew-faces:
+  en: 732171a999049e74
+  zh: 29add66683ac0239
+/deepseek-ai-dsh-crew-faces/summary:
+  en: fa2c991f0ba420ff
+  zh: 5a79c7ffbefabe38
+/deepseek-ai-dsh-crew-faces/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: b00dddf4c88f0a45
+/deepseek-ai-dsh-crew-faces/use-this-package:
+  en: feb411e00685922d
+  zh: 4034878e1390eaf6
+/deepseek-ai-dsh-crew-faces/understand-the-implementation:
+  en: 56a9346e3db0152d
+  zh: 7ee8a4d1ea13b803
+/deepseek-ai-dsh-crew-faces/further-exploration:
+  en: 36d906ef9e0464bf
+  zh: 5a49119b97d2ec08
+/deepseek-ai-dsh-crew-faces/model-experience:
+  en: ff60fda60100a1d0
+  zh: d3df0ed6f6166762
+/deepseek-ai-dsh-crew-faces/model-experience/kv-cache-effect:
+  en: ca75c51c89c2c9b0
+  zh: 477b768cc9dcda1a
+/deepseek-ai-dsh-crew-faces/known-limitations-and-deferred-work:
+  en: 9196cfc3605b9761
+  zh: 91af04bacf3585aa
+/deepseek-ai-dsh-crew-faces/known-limitations-and-deferred-work/dev-note:
+  en: 47713bb5d8aac71f
+  zh: 68c55d987308da7b

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+---
+description: "SVG faces for crew agents: one of four bodies, a colour and two blinking pill eyes, derived deterministically from the agent id."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-agent-crew-faces
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Crew surfaces show each agent as a small face. `CrewFace` draws it as SVG on a 100x100 viewBox: one of four bodies (orb, block, drop, bean) in one of six colours, with two pill eyes and a blink every few seconds. The agent id selects body, colour and blink phase, so an agent keeps its face across reloads and machines. The face has no background shape.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+The [crew-agents](../crew-agents/README.md) bundle mounts this client plugin. It provides `ctx.crewFaces`; a browser plugin injects `crewFaces` and draws a face with its `Face` component:
+
+```tsx
+const { Face } = ctx.crewFaces
+
+<Face agentId={agent.id} mood={agent.working ? 'working' : 'idle'} size={32} label={t('crew.face', { name: agent.name })} />
+```
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `agentId` | required | Stable agent id; selects body, colour and blink phase |
+| `mood` | `idle` | `working` moves both eyes up and right |
+| `design` | unset | `{ body, color }` replacing the body and colour derived from the id; the id still sets the blink phase |
+| `size` | `40` | Width and height in CSS pixels |
+| `label` | unset | Localized accessible name; without it the face is decorative and `aria-hidden` |
+| `className` | unset | Class on the `svg` element |
+
+`ctx.crewFaces.geometry(agentId, mood)`, also exported as `faceGeometry`, returns the same face as data (body, colour, eye colour, body parts, eyes and blink offset) for callers that draw it themselves or compare faces.
+
+Plugins share the component through the service rather than importing it, because client bundles may not import another plugin's values.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+A 32-bit FNV-1a hash of the id selects the body from its low bits, the colour from bits 8 and up, and the blink offset from bits 16 and up.
+
+| Body | Parts | Rotation | Face circle (cx, cy, r) |
+|---|---|---|---|
+| orb | circle (50,52) r38 | none | (50, 52, 38) |
+| block | circles r11 at (27,27) and (73,27), 68x62 rect at (16,24) rx16 | none | (50, 56, 32) |
+| drop | path `M50 10C58 22 86 44 86 62A36 36 0 0 1 14 62C14 44 42 22 50 10Z` | -26° about (50,60) | (54, 58, 34) |
+| bean | 54x80 rect at (24,12) rx27 | -16° about (51,52) | (52, 46, 30) |
+
+The face circle positions the eyes and is never drawn. Eye 1 is centred at (cx+0.2r, cy-0.36r), 0.29r wide and 0.52r tall, rotated -20°. Eye 2 is centred at (cx+0.6r, cy-0.47r), 0.8 times eye 1's width and 0.76 times its height, rotated -22°. Each eye is a rect whose `rx` is half its width. The `working` mood moves both centres 0.06r right and 0.06r up.
+
+Body colours are `#0B0B0C`, `#4D6BFE`, `#E8B4A0`, `#A8C7A1`, `#C9B6E4` and `#F2D16B`. They identify an agent, so they stay fixed across themes. Eyes are `#17181A`, or white on the `#0B0B0C` body.
+
+The blink is a CSS-module animation on both eyes; each face sets `--crew-blink-delay` from its id. Each eye scales to 10% height for a moment of a 5-second cycle, phase-shifted per id. `prefers-reduced-motion: reduce` stops it.
+
+| Source | Contents |
+|---|---|
+| [`src/geometry.ts`](src/geometry.ts) | Hash, bodies, colours and eye placement |
+| [`src/client/CrewFace.tsx`](src/client/CrewFace.tsx) | SVG component |
+| [`src/client/CrewFace.module.css`](src/client/CrewFace.module.css) | Blink |
+| [`src/client/index.ts`](src/client/index.ts) | `ctx.crewFaces` service |
+| [`tests/`](tests/) | Geometry and markup tests |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [ui-primitives](../../client/ui-primitives/README.md) — the shared React atoms crew pages compose with this face.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the package is a browser-side face component that registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Two agents can share a face: there are 24 body and colour combinations.
+- Body colours do not follow the light or dark theme, so a near-black body has low contrast on a dark surface.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+The markup tests render with `react-dom/server` in the Node lane because the face has no interaction.
+
+</details>

package/README.zh.md

@@ -0,0 +1,113 @@
+---
+description: "Crew 智能体的 SVG 头像：四种身体之一、一种颜色和两只会眨的胶囊形眼睛，均由智能体 ID 确定性地推导。"
+kind: "package-reference"
+---
+
+# dsh-agent-crew-faces
+
+[English](README.md) | 中文
+
+## 概述
+
+Crew 界面把每个智能体显示为一个小头像。`CrewFace` 在 100x100 的 viewBox 上以 SVG 绘制它：四种身体（orb、block、drop、bean）之一，六种颜色之一，两只胶囊形眼睛，每隔几秒眨一次眼。智能体 ID 决定身体、颜色和眨眼相位，因此同一智能体在重新加载和不同机器上保持相同头像。头像没有背景形状。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [实现原理](#understand-the-implementation)
+- [延伸阅读](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+[crew-agents](../crew-agents/README.zh.md) bundle 挂载本客户端插件。它提供 `ctx.crewFaces`；浏览器插件注入 `crewFaces`，并用其 `Face` 组件绘制头像：
+
+```tsx
+const { Face } = ctx.crewFaces
+
+<Face agentId={agent.id} mood={agent.working ? 'working' : 'idle'} size={32} label={t('crew.face', { name: agent.name })} />
+```
+
+| 属性 | 默认值 | 含义 |
+|---|---|---|
+| `agentId` | 必填 | 稳定的智能体 ID；决定身体、颜色和眨眼相位 |
+| `mood` | `idle` | `working` 使两只眼睛向右上方移动 |
+| `design` | 未设置 | `{ body, color }`，替换由 ID 推导的身体和颜色；眨眼相位仍由 ID 决定 |
+| `size` | `40` | 宽度和高度，单位为 CSS 像素 |
+| `label` | 未设置 | 已本地化的无障碍名称；未提供时头像为装饰性并设置 `aria-hidden` |
+| `className` | 未设置 | `svg` 元素上的类名 |
+
+`ctx.crewFaces.geometry(agentId, mood)`（也以 `faceGeometry` 导出）以数据形式返回同一头像（身体、颜色、眼睛颜色、身体部件、眼睛和眨眼偏移），供自行绘制或比较头像的调用方使用。
+
+插件通过该服务共享组件而不是直接导入，因为客户端 bundle 不能导入其他插件的值。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 实现原理
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+ID 的 32 位 FNV-1a 哈希以低位选择身体，以第 8 位起的位选择颜色，以第 16 位起的位选择眨眼偏移。
+
+| 身体 | 部件 | 旋转 | 脸部圆 (cx, cy, r) |
+|---|---|---|---|
+| orb | 圆 (50,52) r38 | 无 | (50, 52, 38) |
+| block | (27,27) 和 (73,27) 处 r11 的圆，(16,24) 处 68x62、rx16 的矩形 | 无 | (50, 56, 32) |
+| drop | 路径 `M50 10C58 22 86 44 86 62A36 36 0 0 1 14 62C14 44 42 22 50 10Z` | 绕 (50,60) 旋转 -26° | (54, 58, 34) |
+| bean | (24,12) 处 54x80、rx27 的矩形 | 绕 (51,52) 旋转 -16° | (52, 46, 30) |
+
+脸部圆用于定位眼睛，从不绘制。眼睛 1 的中心位于 (cx+0.2r, cy-0.36r)，宽 0.29r、高 0.52r，旋转 -20°。眼睛 2 的中心位于 (cx+0.6r, cy-0.47r)，宽度为眼睛 1 的 0.8 倍、高度为其 0.76 倍，旋转 -22°。每只眼睛是 `rx` 等于其宽度一半的矩形。`working` 情绪使两个中心各向右、向上移动 0.06r。
+
+身体颜色为 `#0B0B0C`、`#4D6BFE`、`#E8B4A0`、`#A8C7A1`、`#C9B6E4` 和 `#F2D16B`。它们用于识别智能体，因此不随主题变化。眼睛为 `#17181A`，在 `#0B0B0C` 身体上为白色。
+
+眨眼是作用于两只眼睛的 CSS module 动画；每个头像根据 ID 设置 `--crew-blink-delay`。每只眼睛在 5 秒周期中短暂缩放到 10% 高度，相位按 ID 偏移。`prefers-reduced-motion: reduce` 会停止动画。
+
+| 源文件 | 内容 |
+|---|---|
+| [`src/geometry.ts`](src/geometry.ts) | 哈希、身体、颜色和眼睛位置 |
+| [`src/client/CrewFace.tsx`](src/client/CrewFace.tsx) | SVG 组件 |
+| [`src/client/CrewFace.module.css`](src/client/CrewFace.module.css) | 眨眼 |
+| [`src/client/index.ts`](src/client/index.ts) | `ctx.crewFaces` 服务 |
+| [`tests/`](tests/) | 几何与标记测试 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [ui-primitives](../../client/ui-primitives/README.zh.md) — crew 页面与本头像组合使用的共享 React 基础组件。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，本包是浏览器端头像组件，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送模型提供方请求。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 两个智能体可能共用同一头像：身体与颜色共有 24 种组合。
+- 身体颜色不随浅色或深色主题变化，因此近黑色身体在深色背景上对比度较低。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作背景——点击展开</summary>
+
+由于头像没有交互，标记测试在 Node 通道中使用 `react-dom/server` 渲染。
+
+</details>

package/lib/client.js

@@ -0,0 +1,274 @@
+window.__ModuleLoader__.load({
+	id: "dsh-agent-crew-faces",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react_jsx_runtime = require("react/jsx-runtime");
+		//#region lib/types/geometry.js
+		/** Deterministic face geometry for a crew agent on a 100x100 viewBox. */
+		/** Bodies in hash order. */
+		const CREW_BODIES = [
+			"orb",
+			"block",
+			"drop",
+			"bean"
+		];
+		/** Body fills in hash order; `#0B0B0C` takes white eyes. */
+		const CREW_COLORS = [
+			"#0B0B0C",
+			"#4D6BFE",
+			"#E8B4A0",
+			"#A8C7A1",
+			"#C9B6E4",
+			"#F2D16B"
+		];
+		const DARK_BODY = "#0B0B0C";
+		const DARK_EYE = "#17181A";
+		const LIGHT_EYE = "#FFFFFF";
+		/** Working-mood eye offset as a fraction of the face radius. */
+		const WORKING_SHIFT = .06;
+		const SHAPES = {
+			orb: { parts: [{
+				kind: "circle",
+				cx: 50,
+				cy: 52,
+				r: 38
+			}] },
+			block: { parts: [
+				{
+					kind: "circle",
+					cx: 27,
+					cy: 27,
+					r: 11
+				},
+				{
+					kind: "circle",
+					cx: 73,
+					cy: 27,
+					r: 11
+				},
+				{
+					kind: "rect",
+					x: 16,
+					y: 24,
+					width: 68,
+					height: 62,
+					rx: 16
+				}
+			] },
+			drop: {
+				parts: [{
+					kind: "path",
+					d: "M50 10C58 22 86 44 86 62A36 36 0 0 1 14 62C14 44 42 22 50 10Z"
+				}],
+				rotate: [
+					-26,
+					50,
+					60
+				]
+			},
+			bean: {
+				parts: [{
+					kind: "rect",
+					x: 24,
+					y: 12,
+					width: 54,
+					height: 80,
+					rx: 27
+				}],
+				rotate: [
+					-16,
+					51,
+					52
+				]
+			}
+		};
+		/** Face circle `(cx, cy, r)` per body; the eyes are placed relative to it and it is never drawn. */
+		const FACE_CIRCLES = {
+			orb: [
+				50,
+				52,
+				38
+			],
+			block: [
+				50,
+				56,
+				32
+			],
+			drop: [
+				54,
+				58,
+				34
+			],
+			bean: [
+				52,
+				46,
+				30
+			]
+		};
+		/**
+		* 32-bit FNV-1a hash of a string.
+		* @param text - input, hashed by UTF-16 code unit.
+		* @returns unsigned 32-bit hash.
+		*/
+		function hash(text) {
+			let value = 2166136261;
+			for (let index = 0; index < text.length; index++) {
+				value ^= text.charCodeAt(index);
+				value = Math.imul(value, 16777619);
+			}
+			return value >>> 0;
+		}
+		/**
+		* Place both eyes on a face circle.
+		* @param body - body whose face circle the eyes follow.
+		* @param mood - `working` shifts both eyes up and right.
+		* @returns the larger eye, then the smaller one.
+		*/
+		function eyesFor(body, mood) {
+			const [cx, cy, r] = FACE_CIRCLES[body];
+			const shift = mood === "working" ? WORKING_SHIFT * r : 0;
+			const width = .29 * r;
+			const height = .52 * r;
+			const small = {
+				width: .8 * width,
+				height: .76 * height
+			};
+			return [{
+				cx: cx + .2 * r + shift,
+				cy: cy - .36 * r - shift,
+				width,
+				height,
+				rx: width / 2,
+				rotate: -20
+			}, {
+				cx: cx + .6 * r + shift,
+				cy: cy - .47 * r - shift,
+				...small,
+				rx: small.width / 2,
+				rotate: -22
+			}];
+		}
+		/**
+		* Derive one agent's face from its id; the same id always yields the same body, colour and blink phase, and an
+		* explicit design replaces the derived body and colour.
+		* @param agentId - stable agent identifier.
+		* @param mood - current expression.
+		* @param design - body and colour to use instead of the derived ones.
+		* @returns the face to draw.
+		*/
+		function faceGeometry(agentId, mood = "idle", design) {
+			const value = hash(agentId);
+			const body = design?.body ?? CREW_BODIES[value % CREW_BODIES.length] ?? "orb";
+			const color = design?.color ?? CREW_COLORS[(value >>> 8) % CREW_COLORS.length] ?? DARK_BODY;
+			return {
+				body,
+				color,
+				eyeColor: color === DARK_BODY ? LIGHT_EYE : DARK_EYE,
+				shape: SHAPES[body],
+				eyes: eyesFor(body, mood),
+				blinkDelayMs: (value >>> 16) % 4e3
+			};
+		}
+		//#endregion
+		//#region \0dsh-css:/Users/tushar/Developer/deepseek-harness-fork/packages/experimental/crew-faces/src/client/CrewFace.module.css.mjs
+		const css = ".PJWiWW_eye{transform-box:fill-box;transform-origin:50%;animation:PJWiWW_blink 5s var(--crew-blink-delay,0s) infinite}@keyframes PJWiWW_blink{0%,94%,to{transform:scaleY(1)}97%{transform:scaleY(.1)}}@media (prefers-reduced-motion:reduce){.PJWiWW_eye{animation:none}}";
+		const tagId = "dsh-agent-crew-faces/CrewFace.module.css";
+		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
+			const tag = document.createElement("style");
+			tag.dataset.plugin = "dsh-agent-crew-faces";
+			tag.dataset.pluginCss = tagId;
+			tag.textContent = css;
+			document.head.appendChild(tag);
+		}
+		var CrewFace_module_css_default = {
+			"blink": "PJWiWW_blink",
+			"eye": "PJWiWW_eye"
+		};
+		//#endregion
+		//#region lib/types/client/CrewFace.js
+		function Part({ part, fill }) {
+			switch (part.kind) {
+				case "circle": return (0, react_jsx_runtime.jsx)("circle", {
+					cx: part.cx,
+					cy: part.cy,
+					r: part.r,
+					fill
+				});
+				case "rect": return (0, react_jsx_runtime.jsx)("rect", {
+					x: part.x,
+					y: part.y,
+					width: part.width,
+					height: part.height,
+					rx: part.rx,
+					fill
+				});
+				case "path": return (0, react_jsx_runtime.jsx)("path", {
+					d: part.d,
+					fill
+				});
+			}
+		}
+		/**
+		* Draw an agent's face on a 100x100 viewBox: body, two pill eyes and a periodic blink, with no background shape.
+		* The blink stops under reduced motion.
+		* @param props - agent id, mood, optional design, size and optional accessible label.
+		* @returns the SVG element.
+		*/
+		function CrewFace({ agentId, mood = "idle", design, size = 40, label, className }) {
+			const face = faceGeometry(agentId, mood, design);
+			const { shape } = face;
+			const bodyTransform = shape.rotate === void 0 ? void 0 : `rotate(${shape.rotate.join(" ")})`;
+			return (0, react_jsx_runtime.jsxs)("svg", {
+				viewBox: "0 0 100 100",
+				width: size,
+				height: size,
+				className,
+				style: { "--crew-blink-delay": `${-face.blinkDelayMs}ms` },
+				"data-body": face.body,
+				"data-mood": mood,
+				...label === void 0 ? { "aria-hidden": true } : {
+					role: "img",
+					"aria-label": label
+				},
+				children: [(0, react_jsx_runtime.jsx)("g", {
+					transform: bodyTransform,
+					children: shape.parts.map((part, index) => (0, react_jsx_runtime.jsx)(Part, {
+						part,
+						fill: face.color
+					}, index))
+				}), face.eyes.map((eye, index) => (0, react_jsx_runtime.jsx)("g", {
+					transform: `rotate(${eye.rotate} ${eye.cx} ${eye.cy})`,
+					children: (0, react_jsx_runtime.jsx)("rect", {
+						className: CrewFace_module_css_default.eye,
+						x: eye.cx - eye.width / 2,
+						y: eye.cy - eye.height / 2,
+						width: eye.width,
+						height: eye.height,
+						rx: eye.rx,
+						fill: face.eyeColor
+					})
+				}, index))]
+			});
+		}
+		//#endregion
+		//#region lib/types/client/index.js
+		/**
+		* Provide `ctx.crewFaces`.
+		* @param ctx - Client plugin context.
+		*/
+		function apply(ctx) {
+			ctx.reflect.provide("crewFaces", {
+				Face: CrewFace,
+				geometry: faceGeometry
+			});
+		}
+		//#endregion
+		exports.CrewFace = CrewFace;
+		exports.apply = apply;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,172 @@
+//#region lib/types/geometry.js
+/** Deterministic face geometry for a crew agent on a 100x100 viewBox. */
+/** Bodies in hash order. */
+const CREW_BODIES = [
+	"orb",
+	"block",
+	"drop",
+	"bean"
+];
+/** Body fills in hash order; `#0B0B0C` takes white eyes. */
+const CREW_COLORS = [
+	"#0B0B0C",
+	"#4D6BFE",
+	"#E8B4A0",
+	"#A8C7A1",
+	"#C9B6E4",
+	"#F2D16B"
+];
+const DARK_BODY = "#0B0B0C";
+const DARK_EYE = "#17181A";
+const LIGHT_EYE = "#FFFFFF";
+/** Working-mood eye offset as a fraction of the face radius. */
+const WORKING_SHIFT = .06;
+const SHAPES = {
+	orb: { parts: [{
+		kind: "circle",
+		cx: 50,
+		cy: 52,
+		r: 38
+	}] },
+	block: { parts: [
+		{
+			kind: "circle",
+			cx: 27,
+			cy: 27,
+			r: 11
+		},
+		{
+			kind: "circle",
+			cx: 73,
+			cy: 27,
+			r: 11
+		},
+		{
+			kind: "rect",
+			x: 16,
+			y: 24,
+			width: 68,
+			height: 62,
+			rx: 16
+		}
+	] },
+	drop: {
+		parts: [{
+			kind: "path",
+			d: "M50 10C58 22 86 44 86 62A36 36 0 0 1 14 62C14 44 42 22 50 10Z"
+		}],
+		rotate: [
+			-26,
+			50,
+			60
+		]
+	},
+	bean: {
+		parts: [{
+			kind: "rect",
+			x: 24,
+			y: 12,
+			width: 54,
+			height: 80,
+			rx: 27
+		}],
+		rotate: [
+			-16,
+			51,
+			52
+		]
+	}
+};
+/** Face circle `(cx, cy, r)` per body; the eyes are placed relative to it and it is never drawn. */
+const FACE_CIRCLES = {
+	orb: [
+		50,
+		52,
+		38
+	],
+	block: [
+		50,
+		56,
+		32
+	],
+	drop: [
+		54,
+		58,
+		34
+	],
+	bean: [
+		52,
+		46,
+		30
+	]
+};
+/**
+* 32-bit FNV-1a hash of a string.
+* @param text - input, hashed by UTF-16 code unit.
+* @returns unsigned 32-bit hash.
+*/
+function hash(text) {
+	let value = 2166136261;
+	for (let index = 0; index < text.length; index++) {
+		value ^= text.charCodeAt(index);
+		value = Math.imul(value, 16777619);
+	}
+	return value >>> 0;
+}
+/**
+* Place both eyes on a face circle.
+* @param body - body whose face circle the eyes follow.
+* @param mood - `working` shifts both eyes up and right.
+* @returns the larger eye, then the smaller one.
+*/
+function eyesFor(body, mood) {
+	const [cx, cy, r] = FACE_CIRCLES[body];
+	const shift = mood === "working" ? WORKING_SHIFT * r : 0;
+	const width = .29 * r;
+	const height = .52 * r;
+	const small = {
+		width: .8 * width,
+		height: .76 * height
+	};
+	return [{
+		cx: cx + .2 * r + shift,
+		cy: cy - .36 * r - shift,
+		width,
+		height,
+		rx: width / 2,
+		rotate: -20
+	}, {
+		cx: cx + .6 * r + shift,
+		cy: cy - .47 * r - shift,
+		...small,
+		rx: small.width / 2,
+		rotate: -22
+	}];
+}
+/**
+* Derive one agent's face from its id; the same id always yields the same body, colour and blink phase, and an
+* explicit design replaces the derived body and colour.
+* @param agentId - stable agent identifier.
+* @param mood - current expression.
+* @param design - body and colour to use instead of the derived ones.
+* @returns the face to draw.
+*/
+function faceGeometry(agentId, mood = "idle", design) {
+	const value = hash(agentId);
+	const body = design?.body ?? CREW_BODIES[value % CREW_BODIES.length] ?? "orb";
+	const color = design?.color ?? CREW_COLORS[(value >>> 8) % CREW_COLORS.length] ?? DARK_BODY;
+	return {
+		body,
+		color,
+		eyeColor: color === DARK_BODY ? LIGHT_EYE : DARK_EYE,
+		shape: SHAPES[body],
+		eyes: eyesFor(body, mood),
+		blinkDelayMs: (value >>> 16) % 4e3
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/** Register the browser-only contribution without Host state. */
+function apply() {}
+//#endregion
+export { CREW_BODIES, CREW_COLORS, FACE_CIRCLES, apply, eyesFor, faceGeometry };

package/lib/types/client/CrewFace.d.ts

@@ -0,0 +1,22 @@
+import { type CrewMood, type FaceDesign } from '../geometry.ts';
+/** Props of {@link CrewFace}. */
+export interface CrewFaceProps {
+    /** Stable agent id; selects body, colour and blink phase. */
+    readonly agentId: string;
+    readonly mood?: CrewMood;
+    /** Body and colour to use instead of the ones derived from the id. */
+    readonly design?: FaceDesign;
+    /** Rendered width and height in CSS pixels. */
+    readonly size?: number;
+    /** Accessible name, already localized by the caller; without it the face is decorative and hidden from assistive technology. */
+    readonly label?: string;
+    readonly className?: string;
+}
+/**
+ * Draw an agent's face on a 100x100 viewBox: body, two pill eyes and a periodic blink, with no background shape.
+ * The blink stops under reduced motion.
+ * @param props - agent id, mood, optional design, size and optional accessible label.
+ * @returns the SVG element.
+ */
+export declare function CrewFace({ agentId, mood, design, size, label, className }: CrewFaceProps): import("react").JSX.Element;
+//# sourceMappingURL=CrewFace.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,31 @@
+/** Provide crew faces to other browser plugins as a Cordis service. */
+import type { ComponentType } from 'react';
+import type { Context } from '@deepseek-ai/cordis';
+import { type CrewMood, type FaceDesign, type FaceGeometry } from '../geometry.ts';
+import { type CrewFaceProps } from './CrewFace.tsx';
+export { CrewFace, type CrewFaceProps } from './CrewFace.tsx';
+/** Face drawing shared with other crew plugins. */
+export interface CrewFaces {
+    /** SVG face component. */
+    readonly Face: ComponentType<CrewFaceProps>;
+    /**
+     * The face as data.
+     * @param agentId - stable agent id.
+     * @param mood - current expression.
+     * @param design - body and colour to use instead of the derived ones.
+     * @returns body, colours, eyes and blink offset.
+     */
+    readonly geometry: (agentId: string, mood?: CrewMood, design?: FaceDesign) => FaceGeometry;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Crew agent faces. */
+        crewFaces: CrewFaces;
+    }
+}
+/**
+ * Provide `ctx.crewFaces`.
+ * @param ctx - Client plugin context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/geometry.d.ts

@@ -0,0 +1,76 @@
+/** Deterministic face geometry for a crew agent on a 100x100 viewBox. */
+/** Body silhouettes a face can take. */
+export type CrewBody = 'orb' | 'block' | 'drop' | 'bean';
+/** An explicit body and colour that replace the ones derived from the id. */
+export interface FaceDesign {
+    readonly body: CrewBody;
+    /** Body fill; `#0B0B0C` takes white eyes. */
+    readonly color: string;
+}
+/** Face expression; `working` shifts both eyes up and right. */
+export type CrewMood = 'idle' | 'working';
+/** Bodies in hash order. */
+export declare const CREW_BODIES: readonly CrewBody[];
+/** Body fills in hash order; `#0B0B0C` takes white eyes. */
+export declare const CREW_COLORS: readonly string[];
+/** One SVG primitive of a body, in viewBox units. */
+export type BodyPart = {
+    readonly kind: 'circle';
+    readonly cx: number;
+    readonly cy: number;
+    readonly r: number;
+} | {
+    readonly kind: 'rect';
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly rx: number;
+} | {
+    readonly kind: 'path';
+    readonly d: string;
+};
+/** A body's parts and the rotation applied to all of them. */
+export interface BodyShape {
+    readonly parts: readonly BodyPart[];
+    /** `[degrees, cx, cy]` for SVG `rotate()`, absent when upright. */
+    readonly rotate?: readonly [number, number, number];
+}
+/** One pill eye: a rect centred at (cx, cy) with `rx` equal to half its width, rotated about its centre. */
+export interface Eye {
+    readonly cx: number;
+    readonly cy: number;
+    readonly width: number;
+    readonly height: number;
+    readonly rx: number;
+    readonly rotate: number;
+}
+/** Everything needed to draw one face. */
+export interface FaceGeometry {
+    readonly body: CrewBody;
+    readonly color: string;
+    readonly eyeColor: string;
+    readonly shape: BodyShape;
+    readonly eyes: readonly [Eye, Eye];
+    /** Blink phase offset in milliseconds, so faces side by side do not blink together. */
+    readonly blinkDelayMs: number;
+}
+/** Face circle `(cx, cy, r)` per body; the eyes are placed relative to it and it is never drawn. */
+export declare const FACE_CIRCLES: Readonly<Record<CrewBody, readonly [number, number, number]>>;
+/**
+ * Place both eyes on a face circle.
+ * @param body - body whose face circle the eyes follow.
+ * @param mood - `working` shifts both eyes up and right.
+ * @returns the larger eye, then the smaller one.
+ */
+export declare function eyesFor(body: CrewBody, mood: CrewMood): [Eye, Eye];
+/**
+ * Derive one agent's face from its id; the same id always yields the same body, colour and blink phase, and an
+ * explicit design replaces the derived body and colour.
+ * @param agentId - stable agent identifier.
+ * @param mood - current expression.
+ * @param design - body and colour to use instead of the derived ones.
+ * @returns the face to draw.
+ */
+export declare function faceGeometry(agentId: string, mood?: CrewMood, design?: FaceDesign): FaceGeometry;
+//# sourceMappingURL=geometry.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,5 @@
+/** Crew agent face geometry; the SVG component is provided to browser plugins as `ctx.crewFaces`. */
+export { CREW_BODIES, CREW_COLORS, FACE_CIRCLES, eyesFor, faceGeometry, type BodyPart, type BodyShape, type CrewBody, type CrewMood, type Eye, type FaceDesign, type FaceGeometry, } from './geometry.ts';
+/** Register the browser-only contribution without Host state. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/locale/de.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Crew-Gesichter",
+    "description": "Zeichnet für jeden Crew-Agenten ein kleines Gesicht, abgeleitet von seiner ID, das andere Crew-Plugins anzeigen."
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Crew faces",
+    "description": "Draws a small face for each crew agent, chosen from its id, for other crew plugins to show."
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Caras de la crew",
+    "description": "Dibuja una pequeña cara para cada agente de la crew, elegida a partir de su id, para que la muestren otros plugins de Crew."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Visages de la crew",
+    "description": "Dessine un petit visage pour chaque agent de la crew, choisi à partir de son identifiant, que les autres plugins Crew affichent."
+  }
+}

package/locale/ja.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "クルーの顔",
+    "description": "各クルーエージェントの ID から小さな顔を描き、他の Crew プラグインで表示できるようにします。"
+  }
+}

package/locale/pt.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Rostos da crew",
+    "description": "Desenha um pequeno rosto para cada agente da crew, escolhido a partir do seu id, para os outros plugins Crew exibirem."
+  }
+}

package/locale/ru.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Лица команды",
+    "description": "Рисует маленькое лицо для каждого агента команды по его идентификатору, чтобы его показывали другие плагины Crew."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Crew 头像",
+    "description": "根据每位 crew 智能体的 ID 绘制一个小头像，供其他 crew 插件显示。"
+  }
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "dsh-agent-crew-faces",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "SVG faces for crew agents, derived deterministically from the agent id",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tusharcora/dsh-agent-crew.git",
+    "directory": "packages/crew-faces"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./locale/*.json": "./locale/*.json"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": []
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0"
+  },
+  "files": [
+    "locale/*.json",
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "LICENSE"
+  ],
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek-harness-plugin",
+    "deepseek",
+    "dsh-agent-crew"
+  ],
+  "author": "Tushar (https://github.com/tusharcora)",
+  "homepage": "https://github.com/tusharcora/dsh-agent-crew#readme",
+  "bugs": {
+    "url": "https://github.com/tusharcora/dsh-agent-crew/issues"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-rc.1 <0.3.0"
+  }
+}