@meta-sam/graphics 0.1.5

package/LICENSE

@@ -0,0 +1,61 @@
+SAM License
+Last Updated: November 19, 2025
+
+“Agreement” means the terms and conditions for use, reproduction, distribution and modification of the SAM Materials set forth herein.
+
+
+“SAM Materials” means, collectively, Documentation and the models, software and algorithms, including machine-learning model code, trained model weights, inference-enabling code, training-enabling code, fine-tuning enabling code, and other elements of the foregoing distributed by Meta and made available under this Agreement.
+
+“Documentation” means the specifications, manuals and documentation accompanying
+SAM Materials distributed by Meta.
+
+
+“Licensee” or “you” means you, or your employer or any other person or entity (if you are entering into this Agreement on such person or entity’s behalf), of the age required under applicable laws, rules or regulations to provide legal consent and that has legal authority to bind your employer or such other person or entity if you are entering in this Agreement on their behalf.
+
+
+“Meta” or “we” means Meta Platforms Ireland Limited (if you are located in or, if you are an entity, your principal place of business is in the EEA or Switzerland) or Meta Platforms, Inc. (if you are located outside of the EEA or Switzerland).
+
+
+“Sanctions” means any economic or trade sanctions or restrictions administered or enforced by the United States (including the Office of Foreign Assets Control of the U.S. Department of the Treasury (“OFAC”), the U.S. Department of State and the U.S. Department of Commerce), the United Nations, the European Union, or the United Kingdom.
+
+
+“Trade Controls” means any of the following: Sanctions and applicable export and import controls.
+
+By using or distributing any portion or element of the SAM Materials, you agree to be bound by this Agreement.
+
+
+1. License Rights and Redistribution.
+
+
+a. Grant of Rights. You are granted a non-exclusive, worldwide, non-transferable and royalty-free limited license under Meta’s intellectual property or other rights owned by Meta embodied in the SAM Materials to use, reproduce, distribute, copy, create derivative works of, and make modifications to the SAM Materials.
+
+b. Redistribution and Use.
+i. Distribution of SAM Materials, and any derivative works thereof, are subject to the terms of this Agreement. If you distribute or make the SAM Materials, or any derivative works thereof, available to a third party, you may only do so under the terms of this Agreement and you shall provide a copy of this Agreement with any such SAM Materials.
+
+
+ii.  If you submit for publication the results of research you perform on, using, or otherwise in connection with SAM Materials, you must acknowledge the use of SAM Materials in your publication.
+
+
+iii. Your use of the SAM Materials must comply with applicable laws and regulations, including Trade Control Laws and applicable privacy and data protection laws.
+iv. Your use of the SAM Materials will not involve or encourage others to reverse engineer, decompile or discover the underlying components of the SAM Materials.
+v. You are not the target of Trade Controls and your use of SAM Materials must comply with Trade Controls. You agree not to use, or permit others to use, SAM Materials for any activities subject to the International Traffic in Arms Regulations (ITAR) or end uses prohibited by Trade Controls, including those related to military or warfare purposes, nuclear industries or applications, espionage, or the development or use of guns or illegal weapons.
+2. User Support. Your use of the SAM Materials is done at your own discretion; Meta does not process any information nor provide any service in relation to such use.  Meta is under no obligation to provide any support services for the SAM Materials. Any support provided is “as is”, “with all faults”, and without warranty of any kind.
+
+
+3. Disclaimer of Warranty. UNLESS REQUIRED BY APPLICABLE LAW, THE SAM MATERIALS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED ON AN “AS IS” BASIS, WITHOUT WARRANTIES OF ANY KIND, AND META DISCLAIMS ALL WARRANTIES OF ANY KIND, BOTH EXPRESS AND IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING OR REDISTRIBUTING THE SAM MATERIALS AND ASSUME ANY RISKS ASSOCIATED WITH YOUR USE OF THE SAM MATERIALS AND ANY OUTPUT AND RESULTS.
+
+4. Limitation of Liability. IN NO EVENT WILL META OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, ARISING OUT OF THIS AGREEMENT, FOR ANY LOST PROFITS OR ANY DIRECT OR INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY OR PUNITIVE DAMAGES, EVEN IF META OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+
+5. Intellectual Property.
+
+
+a. Subject to Meta’s ownership of SAM Materials and derivatives made by or for Meta, with respect to any derivative works and modifications of the SAM Materials that are made by you, as between you and Meta, you are and will be the owner of such derivative works and modifications.
+
+b. If you institute litigation or other proceedings against Meta or any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the SAM Materials, outputs or results, or any portion of any of the foregoing, constitutes infringement of intellectual property or other rights owned or licensable by you, then any licenses granted to you under this Agreement shall terminate as of the date such litigation or claim is filed or instituted. You will indemnify and hold harmless Meta from and against any claim by any third party arising out of or related to your use or distribution of the SAM Materials.
+
+6. Term and Termination. The term of this Agreement will commence upon your acceptance of this Agreement or access to the SAM Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein. Meta may terminate this Agreement if you are in breach of any term or condition of this Agreement. Upon termination of this Agreement, you shall delete and cease use of the SAM Materials. Sections 3, 4 and 7 shall survive the termination of this Agreement.
+
+7. Governing Law and Jurisdiction. This Agreement will be governed and construed under the laws of the State of California without regard to choice of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement. The courts of California shall have exclusive jurisdiction of any dispute arising out of this Agreement.
+
+
+8. Modifications and Amendments. Meta may modify this Agreement from time to time; provided that they are similar in spirit to the current version of the Agreement, but may differ in detail to address new problems or concerns. All such changes will be effective immediately. Your continued use of the SAM Materials after any modification to this Agreement constitutes your agreement to such modification. Except as provided in this Agreement, no modification or addition to any provision of this Agreement will be binding unless it is in writing and signed by an authorized representative of both you and Meta.

package/README.md

@@ -0,0 +1,490 @@
+# @meta-sam/graphics
+
+`@meta-sam/graphics` is an ESM-only, framework-neutral Canvas 2D renderer for
+SAM 3 segmentation results. It retains complete masks and boxes from
+`@meta-sam/parser`, traces masks during asynchronous updates, and creates browser
+`Path2D` objects lazily while rendering.
+
+## Installation
+
+```sh
+npm install @meta-sam/graphics @meta-sam/parser @meta-sam/video
+```
+
+## Image quick start
+
+The renderer accepts image or video results and snapshots from `@meta-sam/parser`.
+Call and await `update()` before `render()`; rendering is synchronous and sees only
+the last successfully committed update.
+
+<!-- readme-example -->
+
+```ts
+import { SegmentationRenderer } from '@meta-sam/graphics';
+import type { ImageSegmentationResult } from '@meta-sam/parser';
+
+const result: ImageSegmentationResult = {
+  media: 'image',
+  revision: 1,
+  records: [
+    {
+      kind: 'mask',
+      order: 0,
+      objectId: 'bus',
+      identity: 'image:*:bus',
+      revision: 1,
+      mask: {
+        encoding: 'one_bit',
+        width: 5,
+        height: 5,
+        payload: '!!!!!(QO(0lu8?',
+      },
+    },
+    {
+      kind: 'box',
+      order: 1,
+      objectId: 'bus',
+      left: 1,
+      top: 1,
+      right: 4,
+      bottom: 4,
+    },
+  ],
+  diagnostics: [],
+  rawOutput: '',
+  outcome: { status: 'completed' },
+};
+
+const canvas = document.querySelector<HTMLCanvasElement>('#overlay');
+if (canvas === null) throw new Error('Missing overlay canvas.');
+
+const context = canvas.getContext('2d');
+if (context === null) throw new Error('Canvas 2D is unavailable.');
+
+const renderer = new SegmentationRenderer();
+await renderer.update(result);
+renderer.render(context, {
+  media: 'image',
+  source: { x: 0, y: 0, width: 5, height: 5 },
+  target: { x: 0, y: 0, width: canvas.width, height: canvas.height },
+});
+
+// Remove retained overlays while keeping the renderer reusable.
+renderer.clear();
+// Permanently release the renderer when ownership ends.
+renderer.dispose();
+```
+
+The mask payload in this example is one complete, canonical `one_bit` payload. A
+real application normally passes parser snapshots to `update()` as they arrive and
+then passes the final result when parsing completes.
+
+## Video and frame selection
+
+Use video results with `media: 'video'` and select the frame to draw with
+`frameIndex`:
+
+```ts
+await renderer.update(videoResult);
+renderer.render(context, {
+  media: 'video',
+  frameIndex: 42,
+  source: { x: 0, y: 0, width: video.videoWidth, height: video.videoHeight },
+  target: { x: 0, y: 0, width: canvas.width, height: canvas.height },
+});
+```
+
+`frameIndex` must be a non-negative safe integer. Records with the same frame index
+are drawn; records without a frame reference are global and are drawn on every
+video frame. The retained result media must match the render options.
+
+## Same-canvas decoded video composition
+
+`renderVideoFrame()` is a small structural adapter for Canvas media players. Its
+context matches the frame, composition/fallback canvases and contexts, frame-index,
+and abort fields supplied by `@meta-sam/video`'s `MediaPlayerRenderContext`, but
+graphics does not import or depend on the video package. It clears the isolated
+composition canvas, draws the decoded frame first, then draws the exact frame-indexed
+SAM overlay. When the media player supplies `fallbackCanvas`/`fallbackCtx`, the helper
+also draws the same decoded frame with the same fit and DPR but without overlays, ready
+for a missed final-frame deadline.
+
+<!-- readme-example -->
+
+```ts
+import {
+  SegmentationRenderer,
+  type VideoFrameCompositionOptions,
+} from '@meta-sam/graphics';
+import type { VideoSegmentationResult } from '@meta-sam/parser';
+import type { IMediaPlayer } from '@meta-sam/video';
+
+declare const player: IMediaPlayer;
+declare const result: VideoSegmentationResult;
+
+const renderer = new SegmentationRenderer();
+await renderer.update(result);
+
+const hiddenIds = new Set<string>();
+let pixelRatio = window.devicePixelRatio || 1;
+const composition: VideoFrameCompositionOptions = {
+  fit: 'contain',
+  devicePixelRatio: () => pixelRatio,
+  hiddenIds,
+};
+
+player.setCustomRender((context) => {
+  renderer.renderVideoFrame(context, composition);
+});
+
+// The visible canvas backing store owns resize policy. After changing its width or
+// height, update pixelRatio if needed and re-render the retained decoded frame.
+pixelRatio = 2;
+await player.forceRender();
+```
+
+`fit` may be `contain` (the default), `cover`, or `fill`. The helper uses the decoded
+frame dimensions as `source`, derives a logical display rectangle from
+`composition.canvas.width / devicePixelRatio` and height, and recomputes `target` on
+every render. Set the visible output canvas backing width and height to the rounded
+logical size times the same DPR before opening or forcing a render. This makes resize
+behavior explicit and also works for offscreen canvases, where CSS dimensions and the
+global device pixel ratio are unavailable.
+
+The helper checks an already-aborted signal before touching the composition canvas and
+returns `false`; otherwise it returns `true` after synchronous composition. The media
+player's isolated canvas and generation fence prevent a render aborted during later
+asynchronous custom work from reaching the visible canvas. `hiddenIds` contains object
+IDs, not mask identities. Callers still own and await `update()` separately, so a render
+while an update is pending sees the prior committed segmentation state.
+
+The lower-level `render()` API remains available for overlay-only canvases and custom
+source/target rectangles.
+
+## Results, records, and updates
+
+Parser snapshots and final results are **cumulative views**, not deltas. Pass the
+complete current view to every `update()` call.
+
+- `update()` calls are serialized in invocation order. Always await the update that
+  must be visible before calling `render()`.
+- Masks and boxes are retained. Text and point records are accepted but are not
+  drawn.
+- Mask records are collapsed by `identity`; the greatest per-mask `revision` wins.
+  At the same revision, conflicting mask data is rejected.
+- Boxes are collapsed by frame and `objectId`; the last box in the accepted view
+  wins.
+- Masks are always drawn before boxes, regardless of record order. An all-zero mask
+  has no path and is skipped.
+- For the same media, a snapshot revision older than the committed snapshot is
+  ignored. At an accepted equal or newer snapshot revision, identities omitted from
+  the cumulative view are removed. A present mask with an older per-mask revision
+  keeps its retained geometry.
+- Changing media starts a fresh retained view even without `{ reset: true }`.
+
+All records in an input count toward resource limits before masks and boxes are
+collapsed.
+
+## Complete mask payloads
+
+Graphics accepts only complete masks with this shape:
+
+```ts
+{
+  encoding: 'one_bit',
+  width: 5,
+  height: 5,
+  payload: '!!!!!(QO(0lu8?'
+}
+```
+
+`width` and `height` must be positive safe integers, their area must be within the
+configured and codec limits, and `payload` must be within the configured and codec
+length limits. During `update()`, the renderer strictly decodes the entire payload,
+verifies decoder finalization, verifies that the representation is canonical, and
+traces the resulting binary raster. Partial, truncated, trailing, invalid, and
+noncanonical payloads reject the update. Unsupported encodings reject the update.
+
+Use `@meta-sam/parser` to produce complete mask records. Graphics does not accept
+streaming mask fragments.
+
+## Source and target rectangles
+
+`source` selects the coordinate-space rectangle to map, and `target` is the canvas
+rectangle to fill. Both require finite coordinates and strictly positive width and
+height; origins may be negative. Graphics clips to `target` and applies this mapping:
+
+```text
+scaleX  = target.width / source.width
+scaleY  = target.height / source.height
+offsetX = target.x - source.x * scaleX
+offsetY = target.y - source.y * scaleY
+```
+
+The axes scale independently; the renderer does not choose a contain or cover fit.
+Use a `source` rectangle in the same coordinate space as mask pixels and box edges.
+Canvas state is enclosed by `save()` and `restore()`, including when drawing throws.
+
+## Visibility and styling
+
+Hide an object without changing retained state by passing its `objectId` in an array
+or `ReadonlySet`:
+
+```ts
+renderer.render(context, {
+  media: 'image',
+  source,
+  target,
+  hiddenIds: new Set(['background', 'person-2']),
+});
+```
+
+A hidden object contributes neither its mask nor its box, and its mask `Path2D` is
+not created. Colors and geometry are intentionally fixed; fill and outline opacity
+are configurable:
+
+- Each `objectId` hashes deterministically to one of eight colors.
+- Every mask is traced once into a marching-squares contour: its vertices are the
+  midpoints of the edges between neighbouring pixel centers, so a straight
+  boundary follows the pixel edge while corners and diagonals are cut at 45°
+  instead of stepping. One closed subpath is emitted per region, holes included.
+- Each closed polygon is then decimated and smoothed. Decimation drops every
+  vertex the boundary passes straight through, so a straight run — or one 45°
+  diagonal — collapses to its two endpoints. The result is emitted as a uniform
+  quadratic B-spline: for the polygon `p₀…pₙ₋₁` the subpath is
+  `M m₀ Q p₁ m₁ Q p₂ m₂ … Q p₀ m₀ Z`, where `mᵢ` is the midpoint of `pᵢpᵢ₊₁`.
+  The curve therefore runs through every edge midpoint and takes each vertex as
+  a control point rather than passing through it. A 1-pixel staircase — what a
+  mask at native video resolution actually is — becomes a curve within about a
+  tenth of a pixel of the line it approximates instead of a visible step; a long
+  edge keeps its own tangent at its midpoint, so decimated straight runs stay
+  straight; and a genuine right-angle corner, which marching squares has already
+  bevelled at 45°, rounds by under half a source pixel. Coordinates are emitted
+  with at most one decimal, exact for the half-pixel vertex lattice and within
+  0.05 pixels for the quarter-pixel midpoints.
+- A contour of at most four vertices — a lone pixel, a two-pixel sliver — keeps
+  its straight segments, so a single pixel still renders as a full half-pixel
+  diamond instead of being smoothed inward.
+- That single path is both filled and stroked, so the body and the edge can never
+  disagree: filled in the object color with the `evenodd` rule, then stroked in the
+  same color with round joins and caps. Fill opacity defaults to `0.35`; contour
+  opacity defaults to `0.8`. The path is cached per mask and counts toward the cache
+  and `maxPathComplexity` limits, which measure the emitted path string; smoothing
+  roughly doubles that string for the same polygon, since a curve carries a control
+  point as well as an endpoint.
+- The contour width defaults to `0.003 × min(source.width, source.height)` — about
+  2.2 pixels for 720p media — expressed in source pixels, so it scales with the
+  source-to-target transform and tracks the media resolution rather than a fixed
+  pixel count. Turn the contour off with `maskOutline: false`, or configure its
+  source-pixel weight and opacity with `maskOutline: { width: 2, opacity: 0.9 }`.
+- Boxes use the same color at `globalAlpha = 1` and a source-coordinate line width
+  of `2 / max(abs(scaleX), abs(scaleY))`.
+- Masks render before boxes.
+
+The renderer does not mutate records. Object colors, contour geometry, box styling,
+draw order, and source transforms are not configurable.
+
+## Lifecycle and transactional behavior
+
+State changes are transactional. Mask validation, decoding, tracing, and aggregate
+limit checks complete before a candidate state commits. If an update rejects, the
+previous retained state and path cache remain available.
+
+- `update(result, { reset: true })` ignores retained media and revisions. The old
+  state and cache are dropped only after the replacement commits successfully.
+- `clear()` removes committed state and cached `Path2D` objects while keeping the
+  renderer reusable. It also fences already queued stale updates before they decode
+  or commit.
+- `dispose()` is idempotent, clears state and cache, and permanently fences queued
+  work. Later `render()` calls throw `RendererDisposedError`; later `update()` calls
+  reject with it. `clear()` after disposal is a no-op.
+
+`render()` never waits for a pending update. It draws the previous committed state
+until that update resolves.
+
+## Browser requirements
+
+Importing the package and calling `update()` do not access `Path2D`. Rendering
+requires a Canvas 2D context and a browser-compatible `globalThis.Path2D` constructor.
+If `Path2D` is absent, `render()` throws `Path2DUnavailableError` before mutating the
+canvas context. Mask `Path2D` objects are created lazily and retained in a bounded
+least-recently-used cache; each render also creates an uncached path for target
+clipping.
+
+## Configuration
+
+<!-- readme-example -->
+
+```ts
+import {
+  SegmentationRenderer,
+  type SegmentationRendererOptions,
+} from '@meta-sam/graphics';
+
+const options: SegmentationRendererOptions = {
+  maskFillOpacity: 0.5,
+  maskOutline: { width: 2, opacity: 0.9 },
+  maxCachedPaths: 128,
+  maxCachedComplexity: 250_000,
+  maxRecords: 20_000,
+  maxMasks: 4_096,
+  maxBoxes: 8_192,
+  maxMaskArea: 16_777_216,
+  maxMaskPayloadLength: 2_000_000,
+  maxPathComplexity: 250_000,
+  maxRetainedComplexity: 1_000_000,
+};
+const renderer = new SegmentationRenderer(options);
+```
+
+| Option                  | Default                                    |
+| ----------------------- | ------------------------------------------ |
+| `maskFillOpacity`       | `0.35`                                     |
+| `maskOutline`           | `true`                                     |
+| `maskOutline.width`     | `0.003 × min(source.width, source.height)` |
+| `maskOutline.opacity`   | `0.8`                                      |
+| `maxCachedPaths`        | `128`                                      |
+| `maxCachedComplexity`   | `250_000`                                  |
+| `maxRecords`            | `20_000`                                   |
+| `maxMasks`              | `4_096`                                    |
+| `maxBoxes`              | `8_192`                                    |
+| `maxMaskArea`           | `16_777_216`                               |
+| `maxMaskPayloadLength`  | `2_000_000`                                |
+| `maxPathComplexity`     | `250_000`                                  |
+| `maxRetainedComplexity` | `1_000_000`                                |
+
+`maskFillOpacity` and `maskOutline.opacity` must be finite numbers in the inclusive
+range from `0` through `1`. An outline with opacity `0` remains enabled and is still
+stroked. `maskOutline` also accepts `true`, `false`, or `{ width }`; width is in source
+pixels and must be finite and greater than zero. Every resource override must be a
+positive safe integer. Invalid constructor options throw `TypeError`. Constructor
+settings are resolved once, so later mutation of an options object has no effect.
+Cache limits evict least-recently-used paths. Other resource limits reject an update
+before it commits.
+
+## Public API
+
+Only the package root is public; deep imports are not supported.
+
+### Runtime exports
+
+| Export                           | Purpose                                                     |
+| -------------------------------- | ----------------------------------------------------------- |
+| `SegmentationRenderer`           | Retain parser views and render masks and boxes.             |
+| `SegmentationGraphicsError`      | Base class for package-specific errors.                     |
+| `UnsupportedMaskEncodingError`   | Reject a mask encoding other than `one_bit`.                |
+| `InvalidMaskPayloadError`        | Reject invalid mask data or a conflicting mask revision.    |
+| `SegmentationResourceLimitError` | Reject an update that exceeds a configured resource limit.  |
+| `InvalidRenderOptionsError`      | Reject invalid result, frame, rectangle, or transform data. |
+| `RendererDisposedError`          | Reject operations after permanent disposal.                 |
+| `Path2DUnavailableError`         | Report a missing browser `Path2D` implementation.           |
+
+### Type exports
+
+- `Rectangle`
+- `SegmentationCanvasContext`
+- `MaskOutlineOptions`
+- `SegmentationRendererOptions`
+- `SegmentationUpdateOptions`
+- `ImageRenderOptions`
+- `VideoRenderOptions`
+- `SegmentationRenderOptions`
+- `VideoFrameCompositionContext`
+- `VideoFrameCompositionOptions`
+- `VideoFrameFit`
+
+Opacity configuration is declared on the renderer options:
+
+```ts
+interface MaskOutlineOptions {
+  readonly width?: number;
+  /** Contour opacity. Defaults to 0.8. */
+  readonly opacity?: number;
+}
+
+interface SegmentationRendererOptions {
+  /** Mask fill opacity. Defaults to 0.35. */
+  readonly maskFillOpacity?: number;
+  readonly maskOutline?: boolean | MaskOutlineOptions;
+  // Resource limit options are unchanged.
+}
+```
+
+The primary signatures are:
+
+```ts
+class SegmentationRenderer {
+  constructor(options?: SegmentationRendererOptions);
+  update(
+    result: SegmentationResult | SegmentationSnapshot,
+    options?: SegmentationUpdateOptions,
+  ): Promise<void>;
+  render(context: SegmentationCanvasContext, options: SegmentationRenderOptions): void;
+  renderVideoFrame(
+    context: VideoFrameCompositionContext,
+    options?: VideoFrameCompositionOptions,
+  ): boolean;
+  clear(): void;
+  dispose(): void;
+}
+```
+
+`SegmentationResult` and `SegmentationSnapshot` are public types from
+`@meta-sam/parser`.
+
+## Errors
+
+All package-specific errors extend `SegmentationGraphicsError` and expose a stable
+`code`. Handle expected categories with `instanceof`:
+
+```ts
+import { SegmentationGraphicsError, SegmentationRenderer } from '@meta-sam/graphics';
+
+const renderer = new SegmentationRenderer();
+
+try {
+  await renderer.update(result);
+} catch (error) {
+  if (error instanceof SegmentationGraphicsError) {
+    console.error(error.code, error.message, error.cause);
+  } else {
+    throw error;
+  }
+}
+```
+
+| Error                            | `code`                   |
+| -------------------------------- | ------------------------ |
+| `UnsupportedMaskEncodingError`   | `unsupported_encoding`   |
+| `InvalidMaskPayloadError`        | `invalid_mask_payload`   |
+| `SegmentationResourceLimitError` | `resource_limit`         |
+| `InvalidRenderOptionsError`      | `invalid_render_options` |
+| `RendererDisposedError`          | `renderer_disposed`      |
+| `Path2DUnavailableError`         | `path2d_unavailable`     |
+
+Invalid constructor limits throw ordinary `TypeError`. Update failures reject the
+returned promise; render failures throw synchronously.
+
+## Runtime and compatibility
+
+- ESM only. Use `import`; there is no CommonJS export.
+- Supported Node.js versions are `^20.17.0 || >=22.9.0`.
+- The package targets ES2022 and declares `@meta-sam/parser` as its only runtime
+  dependency.
+- Importing and updating are safe without browser globals. Rendering requires Canvas
+  2D and `Path2D`.
+- The package is side-effect-free and publishes only `dist` and this README.
+
+## Related packages
+
+| Package              | Role                                                                      |
+| -------------------- | ------------------------------------------------------------------------- |
+| `@meta-sam/parser`   | Parse structural response events into segmentation snapshots and results. |
+| `@meta-sam/graphics` | Retain mask paths and render Canvas 2D overlays.                          |
+| `@meta-sam/video`    | Decode media into Canvas with packet-exact frame metadata and audio.      |
+| `@meta-sam/react`    | Provide React bindings over the video and graphics packages.              |
+
+## License
+
+The source is licensed under the SAM License. See `LICENSE` in this package or the
+repository root for the license text.

package/dist/contour.d.ts

@@ -0,0 +1,34 @@
+export interface TracedContour {
+    readonly d: string;
+    readonly complexity: number;
+}
+export interface TraceContourOptions {
+    /**
+     * Replace each closed polygon with a uniform quadratic B-spline through its
+     * edge midpoints. Defaults to enabled; pass `false` for the raw polygons.
+     */
+    readonly smooth?: boolean;
+}
+/**
+ * Traces the contour of a binary raster as closed polygons with marching
+ * squares, then smooths each polygon.
+ *
+ * Contour vertices are the midpoints of the edges between neighbouring pixel
+ * centers, so a boundary that runs straight follows the pixel edge exactly
+ * while a corner or a diagonal is cut at 45° instead of stepping. Every
+ * segment is emitted with the filled region on its right, which makes outer
+ * contours wind opposite to the holes they enclose; the caller fills the
+ * result with `evenodd` and strokes the same path.
+ *
+ * The two saddle cases (a filled diagonal pair) are both resolved as a filled
+ * center, matching the eight-connected reading of the raster. That choice is
+ * what makes every crossing the endpoint of exactly one segment, so chaining
+ * the segments is a walk rather than a search.
+ *
+ * A polygon is then decimated — a vertex the contour passes straight through
+ * is dropped, collapsing a straight run to its two endpoints — and emitted as
+ * a quadratic B-spline through the edge midpoints, which turns the 1-pixel
+ * staircase of a native-resolution mask into a smooth boundary. Contours of at
+ * most `SMALL_CONTOUR_VERTICES` vertices keep their straight segments.
+ */
+export declare function traceContour(raster: Uint8Array, width: number, height: number, limit: number, options?: TraceContourOptions): TracedContour;