feat(sia-video-source): add opt-in reader progress feature

[pcfreak30]

Adds an opt-in siaProgressFeature player feature (root exports
siaProgressFeature, selectSiaProgress, SiaProgressState and the React
hook useSiaProgress) that derives reader progress state from real worker
milestones instead of log-text parsing.

The host now dispatches a typed sia-worker-milestone-change event for every
accepted worker LOG, carrying the milestone name, severity, owning
requestId, scalar detail, and a monotonic sequence. Read windows, retries,
byte counts, and stalls update the state; every load boundary resets it.

Also forwards read.retry at debug severity from the worker composition,
which previously dropped the milestone. The feature is not part of
siaFeatures; apps compose it explicitly with
[...videoFeatures, ...siaFeatures, siaProgressFeature].

---

Pull Request Description

Summary

This PR adds an opt-in reader-progress feature for the Sia video source, letting apps surface loading/retrying indicators and byte-count telemetry driven by real worker milestones (structured events) instead of parsing log text.

The feature is deliberately not part of the default siaFeatures — apps opt in by composing siaProgressFeature into their player store and (for React consumers) using the new useSiaProgress() hook. When the feature isn't configured, the selector returns undefined and the default player state stays lean.

What Changed

1. New typed worker-milestone event (sia-video-source.ts)

• SiaVideoSource now dispatches a sia-worker-milestone-change DOM event for every accepted worker LOG message, alongside the existing console forwarding (which is unchanged).
• The payload (SiaWorkerMilestoneDetail) carries the wire facts verbatim: milestone name, severity level, owning requestId, scalar detail fields (defaulted to {}), plus a per-host monotonic sequence that never resets across load boundaries.
• The event follows the same element-to-host forwarding pattern as the existing typed events (load/recovery/source-info).

2. New optional player feature (sia-progress-feature.ts)

• siaProgressFeature (a Video.js v10 PlayerFeature) + selectSiaProgress selector derive a small semantic state from milestone events:
  • reading / reads — opened read windows (via read.window-start / read.window-complete)
  • retrying / retries — retry attempts (via read.retry)
  • bytesRead — cumulative bytes reported by the worker (via bytes.read)
  • last — provenance of the most recent derived milestone (name, position, requestId)
  • read.stalled clears in-flight read/retry state
  • A load boundary (sia-load-change { accepted: false }) resets the whole state; detach/reattach is handled via the feature signal.
• Unknown milestone names are ignored entirely.

3. Milestone severity mapping (session/sia-composition.ts)

• The inline severity mapping was extracted into a reusable milestoneLevel() function.
• read.retry was added as a debug-level forwarded milestone, ensuring a retry attempt is visible to the progress feature (and to debug-severity log consumers) without crowding the log cap.

4. New React hook (react/index.tsx)

• useSiaProgress() subscribes to the same selectSiaProgress state via usePlayer, so React and non-React consumers see identical state. It requires the player store to be built with siaProgressFeature; it also requires the host logger at debug for reader milestones to be forwarded (a louder logger yields an inert state, no errors).

5. Public exports (index.ts)

• siaProgressFeature, selectSiaProgress, SiaProgressState, siaWorkerMilestoneChange, and SiaWorkerMilestoneDetail are now part of the package surface.

6. Tests

• Store-level specs pinning the derivation rules (sia-progress-feature.spec.ts).
• Host specs verifying the milestone event dispatch, sequence monotonicity, post-destroy suppression, and null-requestId pass-through (sia-worker-milestone.host.spec.ts).
• React binding test through a real @videojs/react <Player> with a test-only harness (progress-react-harness.tsx).
• Coverage for the new milestoneLevel mapping (log-wire.spec.ts).

Known Issue (from code review)

• Medium: In sia-progress-feature.ts, the onMilestone switch handles read.stalled and read.window-complete but has no read.error case. A terminal short-read/SDK error (which emits read.error) would leave reading/retrying stuck at true, since nothing clears the in-flight window on that path.

[kody-ai]

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​