Local Font Access API

Draft Community Group Report,

This version:
https://wicg.github.io/local-font-access/
Test Suite:
https://github.com/web-platform-tests/wpt/tree/master/font-access
Issue Tracking:
GitHub
Inline In Spec
Editor:
(Google Inc.)
Former Editor:
Emil A. Eklund

Abstract

This specification documents web browser support for allowing users to grant web sites access to the full set of available system fonts for enumeration, and access to the raw data of fonts, allowing for more detailed custom text rendering.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

logo

1. Introduction

This specification describes a font enumeration API for web browsers which may, optionally, allow users to grant access to the full set of available system fonts. For each font, low-level (byte-oriented) access to an SFNT [SFNT] container or the equivalent provides full font data.

Web developers historically lack anything more than heuristic information about which local fonts are available for use in styling page content. Web developers often include complex lists of font-family values in their CSS to control font fallback in a heuristic way. Generating good fallbacks is such a complex task for designers that tools have been built to help "eyeball" likely-available local matches.

Font enumeration helps:

While the web has its origins as a text-focused medium and user agents provide very high quality typography support, they have limitations that impact some classes of web-based applications:

Professional-quality design and graphics tools have historically been difficult to deliver on the web. These tools provide extensive typographic features and controls as core capabilities.

This API provides these tools access to the same underlying font data that browser layout and rasterization engines use for drawing text. Examples include the OpenType glyf table for glyph vector data, the GPOS table for glyph placement, and the GSUB table for ligatures and other glyph substitution. This information is necessary for these tools in order to guarantee both platform-independence of the resulting output (by embedding vector descriptions rather than codepoints) and to enable font-based art (treating fonts as the basis for manipulated shapes).

2. Goals

The API should:

Although Worker support is called as a goal out above, the API as specified is currently only exposed to Window contexts.

3. Examples

This section is non-normative.

3.1. Enumerating local fonts

The API allows script to enumerate local fonts, including properties about each font.

3.2. Styling with local fonts

Advanced creative tools can offer the ability to style text using all available local fonts. In this case, getting access to the local font name allows the user to select from a richer set of choices:

3.3. Accessing font data

The API allows script to request font data.

3.4. Requesting specific fonts

In some cases, a web application may wish to request access to specific fonts. For example, it may be presenting previously authored content that embeds font names. The queryLocalFonts() call takes a postscriptNames option that scopes the request to fonts identified by PostScript names. Only fonts exactly matching the names in the list will be returned.

User agents may provide a different user interface to support this. For example, if the fingerprinting risk is deemed minimal, the request may be satisfied without prompting the user for permission. Alternately, a picker could be shown with only the requested fonts included.

4. Concepts

The user language is a valid BCP 47 language tag representing either a plausible language or the user’s most preferred language. [BCP47]

4.1. Font Representation

A font representation is some concrete representation of a font. Examples include OpenType, TrueType, bitmap fonts, Type1 fonts, SVG fonts, and future font formats. This specification defines the properties of a font representation as:

A valid PostScript name is a scalar value string with length less than 64 and consisting only of characters in the range U+0021 (!) to U+007E (~) except for the 10 code units U+005B ([), U+005D (]), U+0028 LEFT PARENTHESIS, U+0029 RIGHT PARENTHESIS, U+007B ({), U+007D (}), U+003C (<), U+003E (>), U+002F (/), and U+0025 (%).

4.2. System Fonts

A system font is a font that is available system-wide provided by the operating system.

To read a system font as a font representation is to provide a font representation equivalent to the font. This means providing all properties of a font representation:

This operation can fail if providing a font representation is not possible.

A user agent may use any algorithm to provide a font representation for a system font. In practice, contemporary operating systems and system APIs support fonts that are persisted in SFNT [SFNT] font file formats, such as OpenType, TrueType, Web Open Font Format, etc. which satisfy these requirements, as well as the means to efficiently enumerate font collections with these common name properties provided for each font.

To get all system font representations, run these steps:
  1. Let fonts be a list of all system fonts.

  2. Let result be a new list.

  3. For each font in fonts.

    1. Let representation be font read as a font representation. On failure, continue.

    2. If the user agent determines that the user should never expose the font to the web, then it may continue.

    3. Append representation to result.

  4. Return result.

5. Permissions Integration

Enumeration of local fonts requires a permission to be granted.

5.1. Permissions

The Local Font Access API is a default powerful feature that is identified by the name "local-fonts".

File bug against [PERMISSIONS], to add to the registry.

When the queryLocalFonts() API is invoked, the user agent may present a list of font choices, a yes/no choice, or other interface options. The user agent should present the results of the choice in the permission in an appropriate way. For example, if the user has selected a set of fonts to expose to the site and further API calls will return the same set of fonts, the permission state could be "granted". If the user will be prompted again, the permission state could be "prompt".

5.2. Permissions policy

This specification defines a policy-controlled feature identified by the string "local-fonts". Its default allowlist is 'self'.

File bug against [PERMISSIONS-POLICY] to add policy to its list.

The default allowlist of 'self' allows usage of this feature on same-origin nested frames by default but prevents access by third-party content.

Third-party usage can be selectively enabled by adding the allow="local-fonts" attribute to an iframe element:

<iframe src="https://example.com" allow="local-fonts"></iframe>

Alternatively, this feature can be disabled completely in first-party contexts by specifying the permissions policy in an HTTP response header:

Permissions-Policy: local-fonts 'none'

See [PERMISSIONS-POLICY] for more details.

6. API

6.1. Font task source

The font task source is a new generic task source which is used for all tasks that are queued in this specification.

6.2. Font manager

await self . queryLocalFonts()
await self . queryLocalFonts({ postscriptNames: [ ... ] })

Asynchronously query for available/allowed fonts. If successful, the returned promise resolves to an array of FontData objects.

If the method is not called while the document has transient activation (e.g. in response to a click event), the returned promise will be rejected.

The user will be prompted for permission for access local fonts or to select fonts to provide to the site. If the permission is not granted, the returned promise will rejected.

If the postscriptNames option is given, then only fonts with matching PostScript names will be included in the results.

[SecureContext]
partial interface Window {
  Promise<sequence<FontData>> queryLocalFonts(optional QueryOptions options = {});
};

dictionary QueryOptions {
  sequence<DOMString> postscriptNames;
};
The queryLocalFonts(options) method steps are:
  1. Let promise be a new promise.

  2. Let descriptor be a PermissionDescriptor with its name set to "local-fonts".

  3. If this’s relevant settings object's origin is an opaque origin, then reject promise with a "SecurityError" DOMException, and return promise.

  4. If this’s relevant global object's associated Document is not allowed to use the policy-controlled feature named "local-fonts", then reject promise with a "SecurityError" DOMException, and return promise.

  5. If this’s relevant global object does not have transient activation, then reject promise with a "SecurityError" DOMException, and return promise.

  6. Otherwise, run these steps in parallel:

    1. Let system fonts be the result of getting all system font representations.

    2. Let selectable fonts be a new list.

    3. For each font representation in system fonts, run these steps:

      1. Let postscriptName be representation’s PostScript name.

      2. Assert: postscriptName is a valid PostScript name.

      3. If options["postscriptNames"] exists and options["postscriptNames"] does not contain postscriptName, then continue.

      4. Append a new FontData instance associated with representation to selectable fonts.

    4. Prompt the user to choose one or more items from selectable fonts, with descriptor, and let result be the result. User agents may present a yes/no choice instead of a list of choices, and in that case they should set result to selectable fonts.

    5. If result is "denied", then reject promise with a "NotAllowedError" DOMException, and abort these steps.

    6. Sort result in ascending order by using postscriptName as the sort key and store the result as result.

    7. Queue a task on the font task source to resolve promise with result.

  7. Return promise.

Move to WindowOrWorkerGlobalScope and sort out permission issues.

6.3. The FontData interface

A FontData provides details about a font face. Each FontData has an associated font representation.

fontdata . postscriptName

The PostScript name for the font. Example: "Arial-Bold".

fontdata . fullName

The full font name, including family subfamily names. Example: "Arial Bold"

fontdata . family

The font family name. This corresponds with the CSS font-family property. Example: "Arial"

fontdata . style

The font style (or subfamily) name. Example: "Regular", "Bold Italic"

[Exposed=Window]
interface FontData {
  Promise<Blob> blob();

  // Names
  readonly attribute USVString postscriptName;
  readonly attribute USVString fullName;
  readonly attribute USVString family;
  readonly attribute USVString style;
};
The postscriptName getter steps are:
  1. Let postscriptName be this's PostScript name.

  2. Assert: postscriptName is a valid PostScript name.

  3. Return postscriptName.

The fullName getter steps are to return this's associated font representation's full name.

The family getter steps are to return this's associated font representation's family name.

The style getter steps are to return this's associated font representation's style name.

Consider making FontData serializable objects so that the results of queryLocalFonts() can be passed to Workers.

await blob = fontdata . blob()

Request the underlying bytes of a font. The result blob contains data bytes.

The blob() method steps are:

  1. Let realm be this's relevant Realm.

  2. Let promise be a new promise in realm.

  3. Run these steps in parallel:

    1. Let bytes be this's associated font representation's data bytes.

    2. Let type be `application/octet-stream`.

    3. Queue a task on the font task source to:

    4. Let blob be a new Blob in realm whose contents are bytes and type attribute is type.

    5. Resolve promise with blob.

  4. Return promise.

7. Internationalization considerations

Document internationalization considerations other than string localization, e.g. https://github.com/WICG/local-font-access/issues/72, https://github.com/WICG/local-font-access/issues/59, etc.

7.1. Font Names

The `name` table in OpenType fonts allows names (family, subfamily, etc) to have multilingual strings, using either platform-specific numeric language identifiers or language-tag strings conforming to [BCP47]. For example, a font could have family name strings defined for both `en-US` and `zh-Hant-HK`.

The FontData properties postscriptName, fullName, family, and style are provided by this API simply as strings, using either the US English localization or the user language localization depending on the name, or the first localization as a fallback.

Web applications that need to provide names in other languages can request and parse the `name` table directly.

Should we define an option to the queryLocalFonts() method to specify the desired language for strings (e.g. {lang: 'zh'}), falling back to `en-US` if not present? Or provide access to all the names, e.g. as a map from [BCP47] language tag to name? [Issue #69]

8. Accessibility considerations

There are no known accessibility impacts of this feature.

9. Security considerations

There are no known security impacts of this feature.

10. Privacy considerations

10.1. Fingerprinting

The font data includes:

This provides several "bits of entropy" to distinguish users.

User agents could mitigate this in certain cases (e.g. when the permission is denied, or in Private Browsing / "incognito" mode) by providing an enumeration of a fixed set of fonts provided with the user agent.

User agents may also allow the user to select a set of fonts to make available via the API.

When multiple localizations of font names are provided by a font, the user’s locale is potentially exposed through the font name. User agents should ensure that if a locale is exposed in this way, it’s the same locale that’s exposed by navigator.language.

10.2. Identification

Users from a particular organization could have specific fonts installed. Employees of "Example Co." could all have an "Example Corporate Typeface" installed by their system administrator, which would allow distinguishing users of a site as employees.

There are services which create fonts based on handwriting samples. If these fonts are given names including personally identifiable information (e.g. "Alice’s Handwriting Font"), then personally identifiable information would be made available. This may not be apparent to users if the information is included as properties within the font, not just the font name.

11. Acknowledgements

We’d like to acknowledge the contributions of:

Special thanks (again!) to Tab Atkins, Jr. for creating and maintaining Bikeshed, the specification authoring tool used to create this document.

And thanks to Anne van Kesteren, Chase Phillips, Domenic Denicola, Dominik Röttsches, Igor Kopylov, Jake Archibald, and Jeffrey Yasskin for suggestions, reviews, and other feedback.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[BCP47]
A. Phillips, Ed.; M. Davis, Ed.. Tags for Identifying Languages. September 2009. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc5646
[FileAPI]
Marijn Kruisselbrink; Arun Ranganathan. File API. 4 June 2021. WD. URL: https://www.w3.org/TR/FileAPI/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[OPENTYPE]
OpenType specification. URL: http://www.microsoft.com/typography/otspec/default.htm
[PERMISSIONS]
Marcos Caceres; Mike Taylor. Permissions. 11 March 2022. WD. URL: https://www.w3.org/TR/permissions/
[PERMISSIONS-POLICY]
Ian Clelland. Permissions Policy. 16 July 2020. WD. URL: https://www.w3.org/TR/permissions-policy-1/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SFNT]
Spline/Scalable font format. January 2019. URL: https://www.iso.org/obp/ui/#iso:std:iso-iec:14496:-22:ed-4:v1:en
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[CSS-FONTS-4]
John Daggett; Myles Maxfield; Chris Lilley. CSS Fonts Module Level 4. 21 December 2021. WD. URL: https://www.w3.org/TR/css-fonts-4/
[CSS-FONTS-5]
Myles Maxfield; Chris Lilley. CSS Fonts Module Level 5. 21 December 2021. WD. URL: https://www.w3.org/TR/css-fonts-5/
[TRUETYPE]
TrueType™ Reference Manual. URL: https://developer.apple.com/fonts/TrueType-Reference-Manual/
[WOFF]
Jonathan Kew; Tal Leming; Erik van Blokland. WOFF File Format 1.0. 13 December 2012. REC. URL: https://www.w3.org/TR/WOFF/

IDL Index

[SecureContext]
partial interface Window {
  Promise<sequence<FontData>> queryLocalFonts(optional QueryOptions options = {});
};

dictionary QueryOptions {
  sequence<DOMString> postscriptNames;
};

[Exposed=Window]
interface FontData {
  Promise<Blob> blob();

  // Names
  readonly attribute USVString postscriptName;
  readonly attribute USVString fullName;
  readonly attribute USVString family;
  readonly attribute USVString style;
};

Issues Index

Although Worker support is called as a goal out above, the API as specified is currently only exposed to Window contexts.
File bug against [PERMISSIONS], to add to the registry.
File bug against [PERMISSIONS-POLICY] to add policy to its list.
Move to WindowOrWorkerGlobalScope and sort out permission issues.
Consider making FontData serializable objects so that the results of queryLocalFonts() can be passed to Workers.
Document internationalization considerations other than string localization, e.g. https://github.com/WICG/local-font-access/issues/72, https://github.com/WICG/local-font-access/issues/59, etc.
Should we define an option to the queryLocalFonts() method to specify the desired language for strings (e.g. {lang: 'zh'}), falling back to `en-US` if not present? Or provide access to all the names, e.g. as a map from [BCP47] language tag to name? [Issue #69]