{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "pluma",
  "title": "Pluma",
  "description": "A pen held in the Hand's pinch or tripod writing grip, with helpers that report the nib and grip points.",
  "registryDependencies": [
    "@jbm/tokens",
    "@jbm/scene-geometry",
    "@jbm/mano"
  ],
  "files": [
    {
      "path": "registry/jbm/motion/pluma.tsx",
      "content": "import { useId } from \"react\"\nimport { Mano } from \"./mano\"\nimport { handOutline } from \"../ui/hand\"\nimport { type Pt } from \"../lib/geometry\"\nimport { color, outlineIn } from \"../lib/tokens\"\n/** The hand poses Pluma can hold a pen in. */\nexport const plumaPoses = [\"pinch\", \"write\"] as const\nexport type PlumaPose = (typeof plumaPoses)[number]\nexport type PlumaProps = {\n  /** Grip point in parent units: where the hand holds the pen. Rotation pivots here. */\n  at: Pt\n  /** Rotation in degrees about `at` for the hand and pen together; positive is clockwise. */\n  angle?: number\n  /**\n   * Nib position relative to `at` in parent units, before rotation. The pen runs from the nib\n   * through `at` and on past the knuckles. Defaults to the pose's natural writing slant; the\n   * hand turns about `at` by however far this points away from that slant, so the barrel always\n   * sits in the grip instead of crossing the palm. Its length sets how far the nib reaches.\n   */\n  nibOffset?: Pt\n  /** Hand width in parent units, as in Mano; the pen scales with it. */\n  size?: number\n  /** Draw the Hand. `false` leaves the pen alone, e.g. released on the desk. */\n  hand?: boolean\n  /**\n   * The grip: `pinch` (default) holds the pen in the Hand's pinch; `write` in the Hand's tripod\n   * writing pose, the barrel along the index finger, the thumb's tip over it near the nib, and the\n   * upper barrel over the web and the back of the hand. Both slant the same way at the same angle.\n   */\n  pose?: PlumaPose\n}\n// Hand-viewBox geometry of the pen in each pose. pinch (issue #137): the grip point sits in the\n// pocket between the bent index pad and the thumb; the nib leaves past the thumb tip, far enough that\n// a stretch of barrel shows between the hand's mask gap and the cone (issue #164). The pen weaves with\n// the hand (issue #170): the nib and lower shaft pass behind the thumb and the index pad, and from the\n// grip point, in the open pocket where the change of layer cannot show, the upper shaft crosses in\n// front of the index knuckle toward the viewer.\n// write (issue #177): the pen lies on the traced reference's barrel axis; the grip point is where it\n// crosses the notch between the index and thumb tips, and the tail reaches past the back of the hand.\n// The pose is turned so the default nib slants as pinch's does, so a scene swaps grips at one angle.\n// The pen lies over the hand (the index and the web) and the hand's front (the thumb,\n// handOutline's `front`) lies over the pen.\nconst GEOMETRY = {\n  pinch: { grip: { x: 6.4, y: 12.1 }, nib: { x: -3.2, y: 24.26 }, tail: 17 },\n  write: { grip: { x: 4.967, y: 15.786 }, nib: { x: -0.454, y: 22.653 }, tail: 26.733 },\n} as const\nconst WIDTH = 2.6\nconst CONE = 3.6\n/** The Hand's outline in viewBox units: 30 units across 180 stage px. */\nconst VIEW_OUTLINE = outlineIn(30 / 180)\n/** Where pinch's upper shaft starts over the hand, in viewBox units along the pen from the grip (+ toward the nib). */\nconst OVER_FROM = 0\nconst rotate = (p: Pt, deg: number): Pt => {\n  const r = (deg * Math.PI) / 180\n  return {\n    x: p.x * Math.cos(r) - p.y * Math.sin(r),\n    y: p.x * Math.sin(r) + p.y * Math.cos(r),\n  }\n}\n/** Default nib offset from the grip for a hand `size` wide, before rotation. */\nfunction defaultNib(size: number, pose: PlumaPose): Pt {\n  const s = size / 30\n  const { grip, nib } = GEOMETRY[pose]\n  return { x: (nib.x - grip.x) * s, y: (nib.y - grip.y) * s }\n}\n/**\n * Where a pose holds the pen, relative to the top-left corner of the Hand's box, in parent units\n * for a hand `size` wide: draw Pluma at `at` = corner + this and its hand lands where a bare Hand\n * of that size would.\n */\nexport function plumaGrip(pose: PlumaPose = \"pinch\", size = 180): Pt {\n  const { grip } = GEOMETRY[pose]\n  return { x: +((grip.x * size) / 30).toFixed(4), y: +((grip.y * size) / 30).toFixed(4) }\n}\n/**\n * The nib's point in parent units for a Pluma drawn at `at`/`angle`: feed it to whatever the\n * pen writes (a PaperLine's reveal, a Hilo's start) so ink and pen share one point.\n */\nexport function plumaNib(\n  at: Pt,\n  angle = 0,\n  nibOffset?: Pt,\n  size = 180,\n  pose: PlumaPose = \"pinch\"\n): Pt {\n  const r = rotate(nibOffset ?? defaultNib(size, pose), angle)\n  return { x: at.x + r.x, y: at.y + r.y }\n}\n/**\n * How far right of a caret to put the nib so the pen clears the ink before it: the pen's near\n * edge (cone, then barrel) must stay right of the caret for `rise` parent units above the nib,\n * whatever the rotation. Add it to the caret's x before solving the grip point (see plumaNib).\n */\nexport function plumaCaretGap(\n  angle = 0,\n  rise = 0,\n  nibOffset?: Pt,\n  size = 180,\n  pose: PlumaPose = \"pinch\"\n): number {\n  const s = size / 30\n  const n = rotate(nibOffset ?? defaultNib(size, pose), angle)\n  const len = Math.hypot(n.x, n.y) || 1\n  // Unit vector from the nib back up the pen, and the pen's half width a distance d along it.\n  const u = { x: -n.x / len, y: -n.y / len }\n  const cone = CONE * s\n  const half = (d: number) => ((WIDTH * s) / 2) * Math.min(1, d / cone)\n  const up = -u.y\n  if (up <= 0) return 0\n  const reach = rise / up\n  let worst = 0\n  for (const d of [0, Math.min(cone, reach), reach]) {\n    worst = Math.min(worst, d * u.x - half(d) * Math.abs(u.y))\n  }\n  return +(-worst).toFixed(2)\n}\nconst f = (n: number) => +n.toFixed(2)\n/** A pen held in the Hand's pinch or writing grip; seek-safe, every quantity is a prop. Render inside an <svg>. */\nexport function Pluma({\n  at,\n  angle = 0,\n  nibOffset,\n  size = 180,\n  hand = true,\n  pose = \"pinch\",\n}: PlumaProps) {\n  const s = size / 30\n  const { grip, tail: tailUnits } = GEOMETRY[pose]\n  const nib = nibOffset ?? defaultNib(size, pose)\n  const len = Math.hypot(nib.x, nib.y) || 1\n  // Pen-local frame: +x runs from the grip toward the nib.\n  const dir = (Math.atan2(nib.y, nib.x) * 180) / Math.PI\n  const w = WIDTH * s\n  const cone = CONE * s\n  const tail = tailUnits * s\n  const coneBase = len - cone\n  // The hand follows the pen: turn it by the offset's departure from the natural slant.\n  const natural = defaultNib(size, pose)\n  let follow = dir - (Math.atan2(natural.y, natural.x) * 180) / Math.PI\n  while (follow > 180) follow -= 360\n  while (follow < -180) follow += 360\n  const handAngle = f(angle + follow)\n  const id = useId().replace(/[^\\w-]/g, \"\")\n  const maskId = `pluma-${id}`\n  const cutId = `pluma-cut-${id}`\n  const fillId = `pluma-fill-${id}`\n  const outline = handOutline(pose)\n  // The outline's width in parent units, whatever units the pose's path is authored in.\n  const ink = f(VIEW_OUTLINE * s)\n  const reach = (tail + len + size) * 2\n  const box = { x: f(at.x - reach), y: f(at.y - reach), width: f(2 * reach), height: f(2 * reach) }\n  const handFrame = `translate(${f(at.x)} ${f(at.y)}) rotate(${handAngle}) translate(${f(-grip.x * s)} ${f(-grip.y * s)}) scale(${f(s)}) ${outline.transform}`\n  const penFrame = `translate(${f(at.x)} ${f(at.y)}) rotate(${f(angle + dir)})`\n  const tailCap = `H${f(-tail + w / 2)} A${f(w / 2)} ${f(w / 2)} 0 0 0 ${f(-tail + w / 2)} ${f(w / 2)}`\n  // One silhouette: round tail cap, barrel, and a cone tapering straight on to the nib.\n  const penPath = `M${f(coneBase)} ${f(-w / 2)} ${tailCap} H${f(coneBase)} L${f(len)} 0 Z`\n  const mano = <Mano at={at} pose={pose} size={size} angle={handAngle} anchor={grip} />\n  if (pose === \"write\" && hand) {\n    // The pen lies over the hand and the hand's front (the thumb) over the pen. A mask cuts the pen\n    // along the front plus its outline and a gap half the outline wide, so the barrel stops short of\n    // the thumb's ink. Over the rest of the hand a second mask cuts\n    // the hand's ink along the pen plus the same half-outline gap, sparing the front's own contours,\n    // and the cut is refilled with card only inside the hand's fill; nothing is painted on the page.\n    // One element per subpath, so overlapping parts (the thumb's tip and body) union whatever their\n    // winding.\n    const front = (outline.front ?? \"\").split(/(?=M)/).map((d) => d.trim())\n    const frontWidth = Number(outline.strokeWidth)\n    return (\n      <g>\n        <mask id={maskId} maskUnits=\"userSpaceOnUse\" {...box}>\n          <rect {...box} fill=\"#fff\" />\n          <g transform={handFrame}>\n            {front.map((d) => (\n              <path key={d} d={d} fill=\"#000\" stroke=\"#000\" strokeWidth={frontWidth * 2} strokeLinejoin=\"round\" />\n            ))}\n          </g>\n        </mask>\n        <mask id={cutId} maskUnits=\"userSpaceOnUse\" {...box}>\n          <rect {...box} fill=\"#fff\" />\n          <path transform={penFrame} d={penPath} fill=\"#000\" stroke=\"#000\" strokeWidth={ink} strokeLinejoin=\"round\" />\n          <g transform={handFrame}>\n            {front.map((d) => (\n              <path key={d} d={d} fill=\"#fff\" stroke=\"#fff\" strokeWidth={frontWidth} strokeLinejoin=\"round\" />\n            ))}\n          </g>\n        </mask>\n        <mask id={fillId} maskUnits=\"userSpaceOnUse\" {...box}>\n          <g transform={handFrame}>\n            <path d={outline.d} fill=\"#fff\" />\n          </g>\n        </mask>\n        <g mask={`url(#${fillId})`}>\n          <path transform={penFrame} d={penPath} fill={color.card} stroke={color.card} strokeWidth={ink} strokeLinejoin=\"round\" />\n        </g>\n        <g mask={`url(#${cutId})`}>{mano}</g>\n        <g mask={`url(#${maskId})`}>\n          <g transform={penFrame} data-pluma-nib={`${f(len)}`}>\n            <path d={penPath} fill={color.ink} />\n          </g>\n        </g>\n      </g>\n    )\n  }\n  // pinch: the lower pen passes behind the hand: a mask cuts it along the hand's silhouette plus a\n  // gap half the outline wide, so the two ink edges stay apart. The upper shaft crosses over the\n  // hand: a second mask cuts the hand's ink along the shaft plus the same half-outline gap, so its\n  // contours stop short of the barrel without painting anything on the page. Inside the hand the\n  // gap is refilled with card (clipped to the hand's fill), so it reads as the hand's own paper.\n  // Upper shaft: from the grip point back to the round tail.\n  const upper = `M${f(OVER_FROM * s)} ${f(-w / 2)} ${tailCap} H${f(OVER_FROM * s)} Z`\n  return (\n    <g>\n      {hand && (\n        <mask id={maskId} maskUnits=\"userSpaceOnUse\" {...box}>\n          <rect {...box} fill=\"#fff\" />\n          <g transform={handFrame}>\n            <path\n              d={outline.d}\n              fill=\"#000\"\n              stroke=\"#000\"\n              strokeWidth={outline.strokeWidth * 2}\n              strokeLinejoin=\"round\"\n            />\n          </g>\n        </mask>\n      )}\n      {hand && (\n        <mask id={cutId} maskUnits=\"userSpaceOnUse\" {...box}>\n          <rect {...box} fill=\"#fff\" />\n          <path\n            transform={penFrame}\n            d={upper}\n            fill=\"#000\"\n            stroke=\"#000\"\n            strokeWidth={f(outline.strokeWidth * s)}\n            strokeLinejoin=\"round\"\n          />\n        </mask>\n      )}\n      {hand && (\n        <mask id={fillId} maskUnits=\"userSpaceOnUse\" {...box}>\n          <g transform={handFrame}>\n            <path d={outline.d} fill=\"#fff\" />\n          </g>\n        </mask>\n      )}\n      <g mask={hand ? `url(#${maskId})` : undefined}>\n        <g transform={penFrame} data-pluma-nib={`${f(len)}`}>\n          <path d={penPath} fill={color.ink} />\n        </g>\n      </g>\n      {hand && (\n        <>\n          <g mask={`url(#${fillId})`}>\n            <path\n              transform={penFrame}\n              d={upper}\n              fill={color.card}\n              stroke={color.card}\n              strokeWidth={f(outline.strokeWidth * s)}\n              strokeLinejoin=\"round\"\n            />\n          </g>\n          <g mask={`url(#${cutId})`}>{mano}</g>\n          <g data-pluma-over=\"\">\n            <path transform={penFrame} d={upper} fill={color.ink} />\n          </g>\n        </>\n      )}\n    </g>\n  )\n}\n",
      "type": "registry:component",
      "target": "src/jbm/motion/pluma.tsx"
    }
  ],
  "categories": [
    "UI Bits"
  ],
  "type": "registry:component"
}