feat(web): add percentage bar annotation renderer

.gitignore

@@ -33,3 +33,7 @@ pnpm-debug.log*
 .env
 .env.*
 !.env.example
+
+# Local working notes
+docs/internal/bug-audit-findings.md
+docs/internal/feature-and-bug-proposals.md

demo/src/docs-annotation-renderer.test.ts

@@ -31,9 +31,11 @@ describe("docs annotation renderers", () => {
                   ? ["ellipsesEnabled"]
                   : renderer === "mask-halo"
                     ? ["maskHaloEnabled"]
-                    : renderer === "regions"
-                      ? []
-                      : [`${renderer}Enabled`];
+                    : renderer === "percentage-bar"
+                      ? ["percentageBarsEnabled"]
+                      : renderer === "regions"
+                        ? []
+                        : [`${renderer}Enabled`];
 
       expect(enabled).toEqual(expectedEnabled);
     }
@@ -104,6 +106,19 @@ describe("docs annotation renderers", () => {
       "y: detection.rect.y + detection.rect.height / 2 - radiusY,",
     );
     expect(ellipseSnippet).toContain("alpha: 1,");
+    const percentageBarSnippet = createDocsAnnotationRendererSnippet(
+      "percentage-bar",
+      {
+        ...defaultDemoPresentationSettings,
+        percentageBarFillAlpha: 0.9,
+        percentageBarHeight: 12,
+      },
+    );
+    expect(percentageBarSnippet).toContain(
+      "annotationRenderers.percentageBar({",
+    );
+    expect(percentageBarSnippet).toContain("height: 12");
+    expect(percentageBarSnippet).toContain("alpha: 0.9");
   });
 
   it("exposes marker shape and bounding-box position controls", () => {

demo/src/docs-annotation-renderer.ts

@@ -1,4 +1,8 @@
-import { MarkerShape, type DetectionFrame } from "supervision";
+import {
+  MarkerShape,
+  PercentageBarPlacement,
+  type DetectionFrame,
+} from "supervision";
 import {
   demoMarkerPositionOffsets,
   type DemoMarkerPosition,
@@ -18,6 +22,7 @@ export const docsAnnotationRendererIds = [
   "masks",
   "mask-halo",
   "markers",
+  "percentage-bar",
   "labels",
   "polygons",
   "polylines",
@@ -38,7 +43,7 @@ export interface DocsAnnotationRendererControl {
 }
 
 export type DocsAnnotationRendererSelectSetting =
-  "markerPosition" | "markerShape";
+  "markerPosition" | "markerShape" | "percentageBarPlacement";
 
 export interface DocsAnnotationRendererSelectControl {
   readonly key: DocsAnnotationRendererSelectSetting;
@@ -240,6 +245,43 @@ export const docsAnnotationRenderers: Readonly<
     ],
     title: "Markers",
   },
+  "percentage-bar": {
+    controls: [
+      {
+        key: "percentageBarHeight",
+        label: "Height",
+        max: 24,
+        min: 2,
+        step: 1,
+        unit: "pixels",
+      },
+      {
+        key: "percentageBarFillAlpha",
+        label: "Fill opacity",
+        max: 1,
+        min: 0.1,
+        step: 0.05,
+        unit: "percent",
+      },
+    ],
+    description: "Proportional metric bars anchored to bounding boxes",
+    selects: [
+      {
+        key: "percentageBarPlacement",
+        label: "Placement",
+        options: [
+          { label: "Top", value: PercentageBarPlacement.Top },
+          { label: "Bottom", value: PercentageBarPlacement.Bottom },
+          { label: "Inside Top", value: PercentageBarPlacement.InsideTop },
+          {
+            label: "Inside Bottom",
+            value: PercentageBarPlacement.InsideBottom,
+          },
+        ],
+      },
+    ],
+    title: "Percentage Bar",
+  },
   labels: {
     controls: [
       {
@@ -363,6 +405,7 @@ export function createDocsAnnotationRendererPresentation(
     maskHaloEnabled: renderer === "mask-halo",
     masksEnabled: renderer === "masks" || renderer === "polylines",
     markersEnabled: renderer === "markers",
+    percentageBarsEnabled: renderer === "percentage-bar",
     ...(renderer === "markers"
       ? {
           markerPosition: "bottom-center" as const,
@@ -502,6 +545,18 @@ export function createDocsAnnotationRendererSnippet(
       }),
     }),
   ],
+});`;
+    case "percentage-bar":
+      return `session.setPresentation({
+  renderers: [
+    annotationRenderers.percentageBar({
+      style: new BasePercentageBarStyle({
+        fill: { alpha: ${formatNumber(settings.percentageBarFillAlpha)} },
+        height: ${formatNumber(settings.percentageBarHeight)},
+        placement: PercentageBarPlacement.${percentageBarPlacementMemberNames[settings.percentageBarPlacement]},
+      }),
+    }),
+  ],
 });`;
     case "labels":
       return `session.setPresentation({
@@ -581,6 +636,15 @@ const markerShapeMemberNames: Readonly<Record<MarkerShape, string>> = {
   [MarkerShape.Triangle]: "Triangle",
 };
 
+const percentageBarPlacementMemberNames: Readonly<
+  Record<PercentageBarPlacement, string>
+> = {
+  [PercentageBarPlacement.Top]: "Top",
+  [PercentageBarPlacement.Bottom]: "Bottom",
+  [PercentageBarPlacement.InsideTop]: "InsideTop",
+  [PercentageBarPlacement.InsideBottom]: "InsideBottom",
+};
+
 function formatMarkerCoordinate(axis: "x" | "y", position: DemoMarkerPosition) {
   const offset = demoMarkerPositionOffsets[position][axis];
   const dimension = axis === "x" ? "width" : "height";

demo/src/presentation/demo-presentation.ts

@@ -2,6 +2,7 @@ import {
   BoxStrokeAlignment,
   BoxShape,
   BaseMarkerStyle,
+  BasePercentageBarStyle,
   BaseFocusStyle,
   BaseBoxCornerStyle,
   BaseInteractionStyle,
@@ -16,6 +17,7 @@ import {
   LabelPlacement,
   MarkerShape,
   MaskRenderMode,
+  PercentageBarPlacement,
   annotationRenderers,
   type BoxDrawInstruction,
   type BoxCornerStyle,
@@ -32,6 +34,7 @@ import {
   type MaskStyle,
   type MarkerStyle,
   type MediaRendererPresentation,
+  type PercentageBarStyle,
   type PolygonStyle,
   type PolylineStyle,
   resolveDetectionClassColorStyle,
@@ -62,8 +65,12 @@ export interface DemoPresentationSettings {
   readonly labelsEnabled: boolean;
   readonly masksEnabled: boolean;
   readonly markersEnabled: boolean;
+  readonly percentageBarsEnabled: boolean;
   readonly polygonsEnabled: boolean;
   readonly polylinesEnabled: boolean;
+  readonly percentageBarHeight: number;
+  readonly percentageBarFillAlpha: number;
+  readonly percentageBarPlacement: PercentageBarPlacement;
   readonly boxCornerRadius: number;
   readonly boxCornerLength: number;
   readonly boxCornerStrokeWidth: number;
@@ -124,6 +131,7 @@ export type DemoPresentationLayerSetting =
   | "labelsEnabled"
   | "masksEnabled"
   | "markersEnabled"
+  | "percentageBarsEnabled"
   | "polygonsEnabled"
   | "polylinesEnabled";
 
@@ -140,6 +148,7 @@ const demoPresentationLayerSettings: readonly DemoPresentationLayerSetting[] = [
   "labelsEnabled",
   "masksEnabled",
   "markersEnabled",
+  "percentageBarsEnabled",
   "polygonsEnabled",
   "polylinesEnabled",
 ];
@@ -229,6 +238,10 @@ export const defaultDemoPresentationSettings: DemoPresentationSettings = {
   markerSize: 14,
   markerStrokeWidth: 2,
   markersEnabled: false,
+  percentageBarsEnabled: false,
+  percentageBarFillAlpha: 1,
+  percentageBarHeight: 8,
+  percentageBarPlacement: PercentageBarPlacement.Top,
   polygonFillAlpha: 0.08,
   polygonStrokeWidth: 2,
   polygonsEnabled: true,
@@ -261,6 +274,9 @@ export function createDemoPresentation(
   const markerStyle = settings.markersEnabled
     ? createDemoMarkerStyle(settings)
     : null;
+  const percentageBarStyle = settings.percentageBarsEnabled
+    ? createDemoPercentageBarStyle(settings)
+    : null;
   const polygonStyle = settings.polygonsEnabled
     ? createDemoPolygonStyle(settings)
     : null;
@@ -284,6 +300,7 @@ export function createDemoPresentation(
     labelStyle,
     maskStyle,
     markerStyle,
+    percentageBarStyle,
     polygonStyle,
     polylineStyle,
     maskHaloStyle,
@@ -302,6 +319,9 @@ export function createDemoPresentation(
       ...(markerStyle
         ? [annotationRenderers.marker({ style: markerStyle })]
         : []),
+      ...(percentageBarStyle
+        ? [annotationRenderers.percentageBar({ style: percentageBarStyle })]
+        : []),
       ...(polygonStyle
         ? [annotationRenderers.polygon({ style: polygonStyle })]
         : []),
@@ -621,6 +641,20 @@ function createDemoMaskStyle(settings: DemoPresentationSettings): MaskStyle {
   };
 }
 
+function createDemoPercentageBarStyle(
+  settings: DemoPresentationSettings,
+): PercentageBarStyle {
+  return new BasePercentageBarStyle({
+    fill: (detection) => ({
+      alpha: settings.percentageBarFillAlpha,
+      color: resolveClassStyle(detection, settings).stroke,
+    }),
+    height: settings.percentageBarHeight,
+    placement: settings.percentageBarPlacement,
+    shouldRender: (detection) => passesConfidenceThreshold(detection, settings),
+  });
+}
+
 function createDemoMaskHaloStyle(
   settings: DemoPresentationSettings,
 ): MaskHaloStyle {

docs/public/annotation-renderers.md

@@ -7,6 +7,7 @@ children:
   - ./annotation-renderers/masks.md
   - ./annotation-renderers/mask-halo.md
   - ./annotation-renderers/markers.md
+  - ./annotation-renderers/percentage-bar.md
   - ./annotation-renderers/labels.md
   - ./annotation-renderers/polygons.md
   - ./annotation-renderers/polylines.md
@@ -44,6 +45,7 @@ motion-gated basketball trajectory rather than inventing geometry at runtime.
 - [Masks](./annotation-renderers/masks.md)
 - [Mask Halo](./annotation-renderers/mask-halo.md)
 - [Markers](./annotation-renderers/markers.md)
+- [Percentage Bar](./annotation-renderers/percentage-bar.md)
 - [Labels](./annotation-renderers/labels.md)
 - [Polygons](./annotation-renderers/polygons.md)
 - [Polylines](./annotation-renderers/polylines.md)

docs/public/annotation-renderers/percentage-bar.md

@@ -0,0 +1,43 @@
+---
+title: Percentage Bar
+summary: Visualize confidence scores or custom metrics as proportional progress bars anchored to detections.
+---
+
+# Percentage Bar
+
+The percentage-bar annotation renderer draws proportional progress indicators
+anchored to a detection's rectangle bounds. It is ideal for visualizing model
+confidence scores, tracking probabilities, or custom progression values
+directly on detections.
+
+<div class="supervision-layer-playground">
+  <iframe
+    data-supervision-playground-src="demo/?embed=annotation-renderer&amp;renderer=percentage-bar"
+    loading="lazy"
+    title="Interactive percentage bar visualization playground"
+  ></iframe>
+</div>
+
+The playground uses the frozen basketball fixture's existing detection bounds
+and confidence scores. Percentage bars are presentation only: they do not change
+the source detection, picking, or editing behavior.
+
+## Add the percentage-bar renderer
+
+```ts
+session.setPresentation({
+  renderers: [
+    annotationRenderers.percentageBar({
+      style: new BasePercentageBarStyle({
+        height: 8,
+        placement: PercentageBarPlacement.Top,
+      }),
+    }),
+  ],
+});
+```
+
+`BasePercentageBarStyle` normalizes detection confidence scores into proportional
+progress indicators. Configure `height`, `placement` (such as `Top`, `Bottom`,
+`InsideTop`, or `InsideBottom`), `background`, and `fill` colors to customize
+the display for your use case.

docs/public/api/styles.ts

@@ -9,6 +9,7 @@ export {
   BaseBoxStyle,
   BaseBoxCornerStyle,
   BaseMarkerStyle,
+  BasePercentageBarStyle,
   BaseFocusStyle,
   BaseInteractionStyle,
   BaseKeypointStyle,
@@ -25,6 +26,7 @@ export {
   KeypointMarkerShape,
   MarkerShape,
   MarkerSizeSpace,
+  PercentageBarPlacement,
   LabelVisibilityMode,
   RegionRendererComposeMode,
   RegionRendererCoverageKind,
@@ -102,6 +104,11 @@ export {
   type MarkerDrawInstruction,
   type MarkerStyle,
   type MarkerStyleContext,
+  type BasePercentageBarStyleOptions,
+  type PercentageBarAnnotationRenderer,
+  type PercentageBarDrawInstruction,
+  type PercentageBarStyle,
+  type PercentageBarStyleContext,
   type MaskHaloAnnotationRenderer,
   MaskRenderMode,
   type MaskStrokeStyle,

packages/core/src/index.ts

@@ -93,6 +93,8 @@ export { BaseMaskStyle } from "#styles/mask-style";
 export type { BaseMaskStyleOptions } from "#styles/mask-style";
 export { BaseMarkerStyle } from "#styles/marker-style";
 export type { BaseMarkerStyleOptions } from "#types/marker-style";
+export { BasePercentageBarStyle } from "#styles/percentage-bar-style";
+export type { BasePercentageBarStyleOptions } from "#types/percentage-bar-style";
 export { BasePolygonStyle } from "#styles/polygon-style";
 export type { BasePolygonStyleOptions } from "#styles/polygon-style";
 export { BasePolylineStyle } from "#styles/polyline-style";
@@ -117,6 +119,7 @@ export {
   type MaskAnnotationRenderer,
   type MaskHaloAnnotationRenderer,
   type MarkerAnnotationRenderer,
+  type PercentageBarAnnotationRenderer,
   type PolygonAnnotationRenderer,
   type PolylineAnnotationRenderer,
   RegionRendererComposeMode,
@@ -247,6 +250,12 @@ export type {
   BoxCornerStyle,
   BoxCornerStyleContext,
 } from "#types/box-corner-style";
+export { PercentageBarPlacement } from "#types/percentage-bar-style";
+export type {
+  PercentageBarDrawInstruction,
+  PercentageBarStyle,
+  PercentageBarStyleContext,
+} from "#types/percentage-bar-style";
 export type {
   EllipseGeometry,
   MarkerGeometry,

packages/core/src/styles/annotation-renderer-presentation.test.ts

@@ -121,6 +121,7 @@ describe("annotation renderer presentation", () => {
       mask: annotationRenderers.mask,
       maskHalo: annotationRenderers.maskHalo,
       marker: annotationRenderers.marker,
+      percentageBar: annotationRenderers.percentageBar,
       polygon: annotationRenderers.polygon,
       polyline: annotationRenderers.polyline,
     } as const;