Add pixel budget controls for video rendition selection

[kixelated]

Summary

Adds a new pixels attribute and property to the <moq-watch> element that controls how video renditions are selected based on pixel constraints. This enables two modes of operation: automatic sizing based on the element's rendered dimensions, or a fixed pixel-area budget for bandwidth control.

Changes

• New PixelsMode type: Union of "auto" (default) or a non-negative number representing total pixel area budget.

• Element attribute and property: Added pixels to the observed attributes list and implemented getter/setter that parse and manage the pixel mode via a Signal.

• Auto mode with ResizeObserver: When pixels is "auto", the element tracks its rendered size using ResizeObserver and feeds maxWidth/maxHeight constraints to the video source, scaled by devicePixelRatio for high-DPI displays. This prevents downloading unnecessarily high-resolution streams for small viewport slots.

• Numeric mode: When pixels is set to a number, it pins a total pixel-area budget (pixels field on the target) and clears dimension constraints so the two don't conflict.

• New byDimensions filter: Added rendition filtering function that respects maxWidth and maxHeight constraints independently. Selects the largest rendition within budget, or falls back to the smallest over-budget option if nothing fits.

• Target type expansion: Extended the Target type with optional maxWidth and maxHeight fields to support dimension-based filtering alongside the existing pixels field.

Implementation Details

• The pixel budget logic runs as a separate Effect scoped to the element, allowing cleanup when the element is destroyed.
• ResizeObserver is seeded with the element's current bounding rect to handle cases where the element is still 0x0 when the observer attaches.
• The parsePixelsMode function handles null/empty/invalid inputs by defaulting to "auto".
• Dimension filtering ranks within-budget renditions by area (largest first) for best quality, matching the behavior of the existing byPixels filter.

https://claude.ai/code/session_013QzaZSQikeDkEmuV8ZdTJE

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 99cb5270-96e5-408b-85b4-44847666dae7

📥 Commits

Reviewing files that changed from the base of the PR and between 0538e55 and 599ef36.

📒 Files selected for processing (2)

• js/watch/src/element.ts
• js/watch/src/video/source.ts

---

Walkthrough

This pull request adds a pixels attribute to the MoqWatch web component that controls video rendition selection. The element now exposes a PixelsMode (number or "auto") that either caps pixel area numerically or automatically adjusts based on rendered size and device pixel ratio. The backend Target type gains optional maxWidth and maxHeight constraints, and a new rendition filter ranks available video dimensions by coded area within those caps, falling back to the smallest over-capacity option when needed.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add pixel budget controls for video rendition selection' clearly and concisely summarizes the main change: introducing pixel budget controls for video rendition selection, which aligns with the file changes adding a pixels attribute/property and dimension-based filtering.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing the new pixels attribute, PixelsMode type, auto/numeric modes, ResizeObserver implementation, byDimensions filter, and Target type expansion—all of which are present in the actual code changes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/add-pixel-constraint-swr9x

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/add-pixel-constraint-swr9x

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[kixelated]

IMO rename to width. All of these are maximums.

[kixelated]

I don't understand why you would ever want to change this from auto? It's confusing, can you delete it entirely?