refactor(cos): use singular requestFileHandle() instead of requestFileHandles()

[tomayac]

Switches from the deprecated plural requestFileHandles([hash]) to the new singular requestFileHandle(hash) API, which returns a FileSystemFileHandle directly rather than a single-element array. Also updates the bundled type definitions to match.

The rename was adopted in the COS spec after a survey of all known real-world implementations found that every call site passed a single-element array and immediately destructured it to one handle — no implementation ever used the plural form as intended.

FYI @nico-martin @xenova — as the author and reviewer of the original COS PR (#1549).

See WICG/cross-origin-storage#61 for details.

[nico-martin]

Thank you very much for the PR. When will the new singular API be available in the browser? And is there a fallback in place for the transition to avoid any syntax errors?

[tomayac]

In the browser we don't know yet, it's already in the extension and it accepts both variants, so no breakage at all.

[nico-martin]

Oh yes, sure. I meant in the extension😄

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[tomayac]

Oh yes, sure. I meant in the extension😄

I mean, it's a very legitimate question ;-)

The unit test failure seems unrelated:

fatal: unable to access 'https://huggingface.co/hf-internal-testing/tiny-random-T5ForConditionalGeneration/': The requested URL returned error: 429

[nico-martin]

The unit test failure seems unrelated:

Yes, we have seen this issue in other places too. We are working on it :)

[xenova]

thanks!

(ps: fixing the 429 CI issues now 😇 -- will merge after that)