@startlibs/utils 1.1.1 → 1.2.0-rc.1

package/lib-yak/yakDomTag.mjs

@@ -0,0 +1,44 @@
+import React from 'react';
+import isPropValid from '@emotion/is-prop-valid';
+
+// Task 13c: @yak/react só filtra props `$`-prefixadas e `undefined` antes de repassar pro
+// elemento real; qualquer prop custom (string, número, objeto) lida por um `styled.<tag>` no yak
+// vaza como atributo no DOM. styled-components v5 evita isso sozinho pra tags string, usando
+// @emotion/is-prop-valid. yakDomTag(tag) devolve um componente equivalente: filtra pelas mesmas
+// regras antes de renderizar `tag`, pra o DOM do yak ficar idêntico ao do sc.
+//
+// Resolvido via `@startlibs/utils/yakDomTag` (exports["./*"] do package.json) — não passa pelo
+// index: só existe nessa saída porque o babel-plugin-startlibs-to-yak importa explicitamente
+// (ver tools/babel-plugin-startlibs-to-yak/domTag.cjs), nunca no fonte sc.
+//
+// Memoizado por nome de tag: `styled(yakDomTag('div'))` precisa devolver sempre o MESMO
+// componente de DOM final pra identidade ficar estável entre `${X}` e composições
+// (`styled(X)`/`styledExtend(X)`) de um mesmo `styled.div` — ver @yak/react runtime, que carrega
+// esse componente até o fim da cadeia de composição.
+//
+// `as` (styled-components troca a tag renderizada com essa prop, ex.: components/src/containers/
+// usePositioning.jsx's Placeholder as={placeholderAs}, form/src/TextInput.jsx's Input
+// as={inputTag}) não é filtrada pelo @emotion/is-prop-valid (`isPropValid('as')` é false) — sem
+// tratar à parte, o yak renderizaria sempre a tag original, ignorando a troca.
+const cache = new Map();
+const yakDomTag = tag => {
+  let Component = cache.get(tag);
+  if (!Component) {
+    Component = /*#__PURE__*/React.forwardRef((props, ref) => {
+      const domProps = {};
+      for (const key in props) {
+        // `as` troca a tag renderizada (como styled-components faz); não é uma prop do DOM.
+        if (key === 'as') continue;
+        if (key === 'className' || isPropValid(key)) domProps[key] = props[key];
+      }
+      domProps.ref = ref;
+      return /*#__PURE__*/React.createElement(props.as || tag, domProps);
+    });
+    Component.displayName = `yakDomTag(${tag})`;
+    cache.set(tag, Component);
+  }
+  return Component;
+};
+
+export { yakDomTag };
+//# sourceMappingURL=yakDomTag.mjs.map

package/lib-yak/yakDomTag.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"yakDomTag.mjs","sources":["../src/yakDomTag.jsx"],"sourcesContent":["import React from 'react'\nimport isPropValid from '@emotion/is-prop-valid'\n\n// Task 13c: @yak/react só filtra props `$`-prefixadas e `undefined` antes de repassar pro\n// elemento real; qualquer prop custom (string, número, objeto) lida por um `styled.<tag>` no yak\n// vaza como atributo no DOM. styled-components v5 evita isso sozinho pra tags string, usando\n// @emotion/is-prop-valid. yakDomTag(tag) devolve um componente equivalente: filtra pelas mesmas\n// regras antes de renderizar `tag`, pra o DOM do yak ficar idêntico ao do sc.\n//\n// Resolvido via `@startlibs/utils/yakDomTag` (exports[\"./*\"] do package.json) — não passa pelo\n// index: só existe nessa saída porque o babel-plugin-startlibs-to-yak importa explicitamente\n// (ver tools/babel-plugin-startlibs-to-yak/domTag.cjs), nunca no fonte sc.\n//\n// Memoizado por nome de tag: `styled(yakDomTag('div'))` precisa devolver sempre o MESMO\n// componente de DOM final pra identidade ficar estável entre `${X}` e composições\n// (`styled(X)`/`styledExtend(X)`) de um mesmo `styled.div` — ver @yak/react runtime, que carrega\n// esse componente até o fim da cadeia de composição.\n//\n// `as` (styled-components troca a tag renderizada com essa prop, ex.: components/src/containers/\n// usePositioning.jsx's Placeholder as={placeholderAs}, form/src/TextInput.jsx's Input\n// as={inputTag}) não é filtrada pelo @emotion/is-prop-valid (`isPropValid('as')` é false) — sem\n// tratar à parte, o yak renderizaria sempre a tag original, ignorando a troca.\nconst cache = new Map()\n\nexport const yakDomTag = (tag) => {\n  let Component = cache.get(tag)\n  if (!Component) {\n    Component = React.forwardRef((props, ref) => {\n      const domProps = {}\n      for (const key in props) {\n        // `as` troca a tag renderizada (como styled-components faz); não é uma prop do DOM.\n        if (key === 'as') continue\n        if (key === 'className' || isPropValid(key)) domProps[key] = props[key]\n      }\n      domProps.ref = ref\n      return React.createElement(props.as || tag, domProps)\n    })\n    Component.displayName = `yakDomTag(${tag})`\n    cache.set(tag, Component)\n  }\n  return Component\n}\n"],"names":["cache","Map","yakDomTag","tag","Component","get","React","forwardRef","props","ref","domProps","key","isPropValid","createElement","as","displayName","set"],"mappings":";;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMA,KAAK,GAAG,IAAIC,GAAG,EAAE,CAAA;AAEVC,MAAAA,SAAS,GAAIC,GAAG,IAAK;AAChC,EAAA,IAAIC,SAAS,GAAGJ,KAAK,CAACK,GAAG,CAACF,GAAG,CAAC,CAAA;EAC9B,IAAI,CAACC,SAAS,EAAE;IACdA,SAAS,gBAAGE,KAAK,CAACC,UAAU,CAAC,CAACC,KAAK,EAAEC,GAAG,KAAK;MAC3C,MAAMC,QAAQ,GAAG,EAAE,CAAA;AACnB,MAAA,KAAK,MAAMC,GAAG,IAAIH,KAAK,EAAE;AACvB;QACA,IAAIG,GAAG,KAAK,IAAI,EAAE,SAAA;AAClB,QAAA,IAAIA,GAAG,KAAK,WAAW,IAAIC,WAAW,CAACD,GAAG,CAAC,EAAED,QAAQ,CAACC,GAAG,CAAC,GAAGH,KAAK,CAACG,GAAG,CAAC,CAAA;AACzE,OAAA;MACAD,QAAQ,CAACD,GAAG,GAAGA,GAAG,CAAA;MAClB,oBAAOH,KAAK,CAACO,aAAa,CAACL,KAAK,CAACM,EAAE,IAAIX,GAAG,EAAEO,QAAQ,CAAC,CAAA;AACvD,KAAC,CAAC,CAAA;AACFN,IAAAA,SAAS,CAACW,WAAW,GAAG,CAAA,UAAA,EAAaZ,GAAG,CAAG,CAAA,CAAA,CAAA;AAC3CH,IAAAA,KAAK,CAACgB,GAAG,CAACb,GAAG,EAAEC,SAAS,CAAC,CAAA;AAC3B,GAAA;AACA,EAAA,OAAOA,SAAS,CAAA;AAClB;;;;"}

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@startlibs/utils",
-  "version": "1.1.1",
+  "version": "1.2.0-rc.1",
   "description": "Startlibs Utils",
   "main": "lib/index.cjs",
   "exports": {
     ".": {
       "source": "./src/index.js",
+      "yak": "./lib-yak/index.mjs",
       "require": "./lib/index.cjs",
       "import": "./lib/index.mjs",
       "default": "./lib/index.mjs"
     },
     "./package.json": "./package.json",
     "./*": {
+      "yak": "./lib-yak/*.mjs",
       "import": "./lib/*.mjs"
     }
   },
@@ -19,11 +21,17 @@
   "source": "./src/index.js",
   "peerDependencies": {
     "@startlibs/core": "*",
+    "@yak/react": "10.0.0",
     "lodash": "^4.17.21",
     "polished": "^2.0.0 || ^3.0.0 || ^4.0.0",
     "react": ">=16.8",
     "styled-components": ">=5"
   },
+  "peerDependenciesMeta": {
+    "@yak/react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@babel/core": "^7.26.0",
     "@babel/plugin-transform-runtime": "^7.26.0",
@@ -35,6 +43,7 @@
     "babel-plugin-styled-components": "^1.10.0",
     "lodash": "^4.17.21",
     "polished": "^2.0.0 || ^3.0.0 || ^4.0.0",
+    "react": "^18.3.1",
     "rollup": "^2.79.2",
     "rollup-plugin-auto-external": "^2.0.0",
     "rollup-plugin-babel": "^4.0.3",
@@ -43,8 +52,8 @@
     "styled-components": "^5.3.11"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "rollup -c"
+    "test": "node --import ./test/register.mjs --test src/**/*.test.mjs",
+    "build": "rollup -c && rollup -c --environment YAK"
   },
   "repository": {
     "type": "git",
@@ -62,10 +71,12 @@
   "homepage": "https://github.com/felipeko/startlibs#readme",
   "dependencies": {
     "@babel/runtime": "^7.20.0",
+    "@emotion/is-prop-valid": "^1.1.0",
     "create-emotion": "10.0.27"
   },
   "files": [
     "lib",
+    "lib-yak",
     "src"
   ],
   "module": "lib/index.mjs",

package/src/animationKeyframes.js

@@ -0,0 +1,10 @@
+import createEmotion from 'create-emotion'
+
+// Saída sc (lib/): o keyframes do emotion, como sempre foi. A saída yak (lib-yak/) usa
+// animationKeyframes.yak.js no lugar deste arquivo (ver tools/rollup.base.mjs).
+const emotion = createEmotion({
+  nonce: (typeof document !== 'undefined' &&
+    (document.querySelector('meta[property="csp-nonce"]') || {}).content) || 'animation_nonce'
+})
+
+export const animationKeyframes = emotion.keyframes

package/src/animationKeyframes.test.mjs

@@ -0,0 +1,75 @@
+import {test, before, after} from 'node:test'
+import assert from 'node:assert/strict'
+
+// oneWayAnimation/twoWayAnimation na saída yak. `styled.js?yak` carrega o grafo como a
+// lib-yak (animationKeyframes.yak.js no lugar de animationKeyframes.js, ver test/jsxLoader.mjs).
+// A saída sc (emotion) não roda aqui: o default do create-emotion é CJS; ela fica igual à de
+// antes, o que tools/compare-lib.sh e as goldens do compat conferem.
+// fixMediaQuery lê `window` no import; sem document, ele não mede nada.
+const adopted = []
+before(() => {
+  globalThis.window = {}
+  globalThis.CSSStyleSheet = class {
+    constructor() {
+      this.cssRules = []
+      adopted.push(this)
+    }
+    insertRule(rule, index) {
+      this.cssRules.splice(index, 0, rule)
+    }
+    replaceSync() {}
+  }
+})
+after(() => {
+  delete globalThis.window
+  delete globalThis.document
+  delete globalThis.CSSStyleSheet
+})
+
+const withDocument = () => {
+  globalThis.document = {
+    adoptedStyleSheets: [],
+    styleSheets: [],
+    querySelector: () => null
+  }
+}
+
+const rules = () => adopted.flatMap((sheet) => sheet.cssRules)
+const squash = (text) => text.replace(/\s+/g, ' ').trim()
+
+test('yak: mesmos offsets de antes (0..100%, frame vazio fica de fora), registrado pelo CSSOM', async () => {
+  const {oneWayAnimation} = await import('./styled.js?yak')
+  withDocument()
+  const name = oneWayAnimation('opacity: 0;', '', 'opacity: 1;')
+  assert.match(name, /^startlibs-animation-[0-9a-z]+$/)
+  const rule = rules().find((r) => r.startsWith(`@keyframes ${name} `))
+  assert.equal(squash(rule), `@keyframes ${name} { 0% { opacity: 0; }100% { opacity: 1; }}`)
+
+  const three = oneWayAnimation('a: 1;', 'a: 2;', 'a: 3;', 'a: 4;')
+  assert.equal(squash(rules().find((r) => r.startsWith(`@keyframes ${three} `))),
+    `@keyframes ${three} { 0% { a: 1; }33% { a: 2; }67% { a: 3; }100% { a: 4; }}`)
+})
+
+test('yak: mesmos frames, mesmo nome e uma regra só; frames diferentes, nomes diferentes', async () => {
+  const {oneWayAnimation, twoWayAnimation} = await import('./styled.js?yak')
+  withDocument()
+  const before = rules().length
+  const a = oneWayAnimation('opacity: 0.25;', 'opacity: 0.5;')
+  assert.equal(oneWayAnimation('opacity: 0.25;', 'opacity: 0.5;'), a)
+  assert.equal(rules().length, before + 1)
+
+  const [enter, leave] = twoWayAnimation('opacity: 0.25;', 'opacity: 0.75;')
+  assert.notEqual(enter, leave)
+  assert.notEqual(enter, a)
+  assert.equal(squash(rules().find((r) => r.startsWith(`@keyframes ${leave} `))),
+    `@keyframes ${leave} { 0% { opacity: 0.75; }100% { opacity: 0.25; }}`)
+})
+
+test('yak: no import (sem document) devolve um nome e registra quando o frame é pedido de novo', async () => {
+  delete globalThis.document
+  const {identityOpacityFrames, oneWayAnimation} = await import('./styled.js?yak')
+  assert.match(identityOpacityFrames, /^startlibs-animation-/)
+  withDocument()
+  assert.equal(oneWayAnimation('opacity: 1;', 'opacity:1;'), identityOpacityFrames)
+  assert.ok(rules().some((r) => r.startsWith(`@keyframes ${identityOpacityFrames} `)))
+})

package/src/animationKeyframes.yak.js

@@ -0,0 +1,30 @@
+import {insertKeyframes} from './insertKeyframes'
+
+// Saída yak (lib-yak/): mesmo contrato do keyframes do emotion (tag de template que devolve o
+// nome da animação), mas registrado pelo CSSOM, sem <style> e sem nonce.
+const interpolate = (value) =>
+  Array.isArray(value) ? value.map(interpolate).join('')
+    : value === null || value === undefined || typeof value === 'boolean' ? ''
+      : String(value)
+
+// djb2: só precisa ser estável e curto; colisão é tratada abaixo.
+const hash = (text) => {
+  let h = 5381
+  for (let i = 0; i < text.length; i++) h = ((h * 33) ^ text.charCodeAt(i)) >>> 0
+  return h.toString(36)
+}
+
+const nameByFrames = new Map()
+const usedNames = new Set()
+
+export const animationKeyframes = (strings, ...values) => {
+  const frames = strings.reduce((text, part, i) => text + part + (i < values.length ? interpolate(values[i]) : ''), '')
+  if (!nameByFrames.has(frames)) {
+    const base = 'startlibs-animation-' + hash(frames)
+    let name = base
+    for (let i = 2; usedNames.has(name); i++) name = base + '-' + i
+    usedNames.add(name)
+    nameByFrames.set(frames, name)
+  }
+  return insertKeyframes(nameByFrames.get(frames), frames)
+}

package/src/fixMediaQuery.js

@@ -1,4 +1,9 @@
+import {fixMediaText} from './fixMediaText'
+
 let fixed = false
+// Each rule may only get the scrollbar width added once, even if its sheet is seen again.
+const patched = new WeakSet()
+
 export const scrollWidth = (function() {
   if (!window.document) return 0
   const html = document.documentElement
@@ -15,28 +20,44 @@ const fixMediaQueryFn = function() {
 
   if (scrollWidth > 0) {
 
-    [].slice.call(document.styleSheets).filter(styleSheet => isValidExternal(styleSheet) || isInline(styleSheet)).forEach(stylesheet => {
-      try {
-        [].slice.call(stylesheet.cssRules || stylesheet.media).filter(rule => rule.constructor === window.CSSMediaRule).forEach(rule => {
-          rule.media.mediaText = rule.media.mediaText.replace(/m(in|ax)-width:\s*(\d|\.)+(px|em)/gi, function(strA) {
-            if (strA.match('px')) {
-              return strA.replace(/\d+px/gi, function(strB) {
-                return parseInt(strB, 10) + scrollWidth + 'px'
-              })
-            }
-            else {
-              return strA.replace(/\d.+?em/gi, function(strB) {
-                return ((parseFloat(strB) * fontSize) + scrollWidth) / fontSize + 'em'
-              })
-            }
-          })
-        })
-      } catch (e) {}
-    })
+    [].slice.call(document.styleSheets).forEach(fixStylesheet)
+    watchLateStylesheets()
   }
 
   fixed = true
 
+  function fixStylesheet(stylesheet) {
+    if (!stylesheet || patched.has(stylesheet) || !(isValidExternal(stylesheet) || isInline(stylesheet))) {
+      return
+    }
+    try {
+      [].slice.call(stylesheet.cssRules).filter(rule => rule.constructor === window.CSSMediaRule).forEach(rule => {
+        rule.media.mediaText = fixMediaText(rule.media.mediaText, scrollWidth, fontSize)
+      })
+      patched.add(stylesheet)
+    } catch (e) {}
+  }
+
+  // Lazy routes add <link>s, and Vite dev and HMR add or rewrite <style>s, after the first pass.
+  function watchLateStylesheets() {
+    new MutationObserver(mutations => mutations.forEach(({target, addedNodes}) => {
+      const owner = target.nodeType === Node.TEXT_NODE ? target.parentNode : target
+      if (owner && owner.nodeName === 'STYLE') {
+        fixStylesheet(owner.sheet)
+      }
+      [].slice.call(addedNodes).forEach(node => {
+        if (node.nodeName === 'STYLE') {
+          fixStylesheet(node.sheet)
+        }
+        if (node.nodeName === 'LINK' && node.rel === 'stylesheet') {
+          // Not parsed yet when added; `load` also fires again if its href changes.
+          node.addEventListener('load', () => fixStylesheet(node.sheet))
+          fixStylesheet(node.sheet)
+        }
+      })
+    })).observe(document.head, {childList: true, subtree: true, characterData: true})
+  }
+
   function sameOrigin(url) {
     const loc = window.location,
       a = document.createElement('a')
@@ -68,4 +89,4 @@ export function fixMediaQuery() {
   } else {
     document.addEventListener('DOMContentLoaded', fixMediaQueryFn)
   }
-}
+}

package/src/fixMediaText.js

@@ -0,0 +1,18 @@
+// Soma a largura da scrollbar aos limites de largura de um mediaText.
+// Reconhece a forma antiga (`max-width: 600px`, `min-width: 37.5em`, que o sc emite) e a
+// sintaxe de intervalo (`width <= 600px`, `width < 600px`, `600px <= width`,
+// `400px < width < 600px`), que o Chromium devolve para o CSS estático do yak.
+// Sem lookbehind de propósito: é erro de sintaxe no Safari < 16.4, e o browserslist do pacote
+// ainda promete Safari 11. O caractere antes de `width` é capturado e devolvido igual, só pra
+// não casar o `width` de `device-width`.
+const LEGACY_OR_WIDTH_FIRST = /(m(?:in|ax)-width\s*:\s*|(?:^|[^-\w])width\s*[<>]=?\s*)([\d.]+)(px|em)/gi
+const VALUE_FIRST = /([\d.]+)(px|em)(\s*[<>]=?\s*width)(?![-\w])/gi
+
+export function fixMediaText(mediaText, scrollWidth, fontSize) {
+  const grow = (value, unit) => unit.toLowerCase() === 'px'
+    ? parseFloat(value) + scrollWidth + unit
+    : ((parseFloat(value) * fontSize) + scrollWidth) / fontSize + unit
+  return mediaText
+    .replace(LEGACY_OR_WIDTH_FIRST, (match, prefix, value, unit) => prefix + grow(value, unit))
+    .replace(VALUE_FIRST, (match, value, unit, suffix) => grow(value, unit) + suffix)
+}

package/src/fixMediaText.test.mjs

@@ -0,0 +1,60 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {readFileSync} from 'node:fs'
+import {fixMediaText} from './fixMediaText.js'
+
+const fix = (mediaText) => fixMediaText(mediaText, 15, 16)
+
+test('forma antiga do sc: max-width/min-width em px', () => {
+  assert.equal(fix('(max-width: 600px)'), '(max-width: 615px)')
+  assert.equal(fix('screen and (min-width: 601px)'), 'screen and (min-width: 616px)')
+  assert.equal(fix('(max-width:600px)'), '(max-width:615px)')
+})
+
+test('forma antiga do sc: em é convertido via font-size', () => {
+  assert.equal(fix('(max-width: 37.5em)'), `(max-width: ${(37.5 * 16 + 15) / 16}em)`)
+})
+
+test('sintaxe de intervalo do yak: <= e >=', () => {
+  assert.equal(fix('(width <= 600px)'), '(width <= 615px)')
+  assert.equal(fix('(width>=601px)'), '(width>=616px)')
+})
+
+test('sintaxe de intervalo estrita: < e >', () => {
+  assert.equal(fix('(width < 600px)'), '(width < 615px)')
+  assert.equal(fix('(width>601px)'), '(width>616px)')
+})
+
+test('sintaxe de intervalo com o valor antes de width', () => {
+  assert.equal(fix('(600px <= width)'), '(615px <= width)')
+  assert.equal(fix('(600px<width)'), '(615px<width)')
+  assert.equal(fix('(400px < width < 600px)'), '(415px < width < 615px)')
+})
+
+test('mantém o caractere antes de width', () => {
+  assert.equal(fix('(width <= 600px)'), '(width <= 615px)')
+  assert.equal(fix('width <= 600px'), 'width <= 615px')
+  assert.equal(fix('not all and (width<600px)'), 'not all and (width<615px)')
+})
+
+test('não mexe em device-width nem em outros media features', () => {
+  assert.equal(fix('(device-width >= 600px)'), '(device-width >= 600px)')
+  assert.equal(fix('(600px <= device-width)'), '(600px <= device-width)')
+  assert.equal(fix('(max-device-width: 600px)'), '(max-device-width: 600px)')
+  assert.equal(fix('(height <= 600px)'), '(height <= 600px)')
+  assert.equal(fix('print'), 'print')
+})
+
+test('várias condições na mesma regra', () => {
+  assert.equal(
+    fix('(min-width: 400px) and (max-width: 600px), (width < 300px)'),
+    '(min-width: 415px) and (max-width: 615px), (width < 315px)'
+  )
+})
+
+test('o fonte não usa lookbehind (quebra Safari < 16.4)', () => {
+  for (const file of ['fixMediaText.js', 'fixMediaQuery.js']) {
+    const src = readFileSync(new URL(file, import.meta.url), 'utf8')
+    assert.doesNotMatch(src, /\(\?<[=!]/, file)
+  }
+})

package/src/formatDate.js

@@ -77,7 +77,7 @@ export function formatDateToPattern(format) {
 }
 
 export function formatDate(date, format, messages,noUTC) {
-  if (!date)
+  if (!date && date !== 0)
     return ''
   const separators = format.replace(escapedValidParts, '\0').split('\0')
   const parts = format.match(escapedValidParts)

package/src/index.js

@@ -4,6 +4,7 @@ export * from './smoothScroll'
 export * from './fixMediaQuery'
 export * from './FetchUtils'
 export * from './styled'
+export * from './insertKeyframes'
 export * from './formatDate'
 export * from './lodashUtils'
 export * from './ActionUtils'

package/src/insertKeyframes.js

@@ -0,0 +1,73 @@
+// Registra um @keyframes pelo CSSOM, sem criar <style> na página: funciona com CSP
+// `style-src 'self'` sem nonce. Ordem de tentativa:
+//   1. uma folha construída (new CSSStyleSheet) em document.adoptedStyleSheets;
+//   2. browser sem folha construída: insertRule numa folha do próprio site já carregada
+//      (de preferência um <link>, que nenhum runtime de CSS-in-JS gerencia);
+//   3. nenhuma das duas: <style> com o nonce do <meta property="csp-nonce">, se houver.
+// Cada nome entra uma vez só; quem chama garante que nome igual é conteúdo igual.
+const inserted = new Set()
+let adoptedSheet = null
+let pageSheet = null
+
+const canAdoptSheets = () =>
+  typeof CSSStyleSheet !== 'undefined' &&
+  'replaceSync' in CSSStyleSheet.prototype &&
+  'adoptedStyleSheets' in document
+
+// Outro código pode reatribuir document.adoptedStyleSheets e tirar a folha da lista: recoloca.
+const getAdoptedSheet = () => {
+  if (!adoptedSheet) adoptedSheet = new CSSStyleSheet()
+  if (document.adoptedStyleSheets.indexOf(adoptedSheet) < 0) {
+    document.adoptedStyleSheets = document.adoptedStyleSheets.concat(adoptedSheet)
+  }
+  return adoptedSheet
+}
+
+// Folha que vale pra tela inteira e cujas regras dá pra ler (folha de outra origem lança erro).
+const isWritable = (sheet) => {
+  if (sheet.disabled || !sheet.ownerNode || !sheet.ownerNode.isConnected) return false
+  if (sheet.media && sheet.media.length && sheet.media.mediaText !== 'all') return false
+  try {
+    return !!sheet.cssRules
+  } catch (e) {
+    return false
+  }
+}
+
+const getPageSheet = () => {
+  if (pageSheet && isWritable(pageSheet)) return pageSheet
+  const sheets = Array.prototype.slice.call(document.styleSheets).filter(isWritable)
+  pageSheet = sheets.filter((sheet) => sheet.ownerNode.tagName === 'LINK')[0] || sheets[0] || null
+  return pageSheet
+}
+
+const appendRule = (sheet, rule) => {
+  try {
+    sheet.insertRule(rule, sheet.cssRules.length)
+  } catch (e) {
+    // regra que o browser não entende: igual a um <style> com ela, só não faz nada
+  }
+}
+
+const appendStyleElement = (name, rule) => {
+  const style = document.createElement('style')
+  style.id = 'startlibs-keyframes-' + name
+  const nonce = (document.querySelector('meta[property="csp-nonce"]') || {}).content
+  if (nonce) style.nonce = nonce
+  style.textContent = rule
+  document.head.appendChild(style)
+}
+
+export const insertKeyframes = (name, frames) => {
+  if (typeof document === 'undefined' || inserted.has(name)) return name
+  inserted.add(name)
+  const rule = '@keyframes ' + name + ' {' + frames + '}'
+  if (canAdoptSheets()) {
+    appendRule(getAdoptedSheet(), rule)
+  } else if (getPageSheet()) {
+    appendRule(pageSheet, rule)
+  } else {
+    appendStyleElement(name, rule)
+  }
+  return name
+}

package/src/insertKeyframes.test.mjs

@@ -0,0 +1,144 @@
+import {test, afterEach} from 'node:test'
+import assert from 'node:assert/strict'
+
+// DOM falso, só o que insertKeyframes lê. Cada teste importa o módulo com uma query diferente
+// pra começar sem estado (folha adotada, nomes já inseridos).
+let instance = 0
+const freshInsertKeyframes = async () => (await import(`./insertKeyframes.js?t${++instance}`)).insertKeyframes
+
+const fakeSheet = ({tagName = 'LINK', media = '', readable = true} = {}) => {
+  const rules = []
+  return {
+    ownerNode: {tagName, isConnected: true},
+    media: {length: media ? 1 : 0, mediaText: media},
+    get cssRules() {
+      if (!readable) throw new Error('SecurityError')
+      return rules
+    },
+    rules,
+    insertRule(rule, index) {
+      rules.splice(index, 0, rule)
+      return index
+    }
+  }
+}
+
+const fakeDocument = ({styleSheets = [], adopted = false, nonce} = {}) => {
+  const appended = []
+  const doc = {
+    styleSheets,
+    appended,
+    head: {appendChild: (el) => appended.push(el)},
+    createElement: (tag) => ({tag}),
+    querySelector: (selector) => selector === 'meta[property="csp-nonce"]' && nonce ? {content: nonce} : null
+  }
+  if (adopted) doc.adoptedStyleSheets = []
+  return doc
+}
+
+class FakeConstructedSheet {
+  constructor() {
+    this.rules = []
+    this.cssRules = this.rules
+  }
+  insertRule(rule, index) {
+    this.rules.splice(index, 0, rule)
+    return index
+  }
+  replaceSync() {}
+}
+
+afterEach(() => {
+  delete globalThis.document
+  delete globalThis.CSSStyleSheet
+})
+
+test('sem document (SSR): devolve o nome e não faz nada', async () => {
+  const insertKeyframes = await freshInsertKeyframes()
+  assert.equal(insertKeyframes('spin', '100% { opacity: 0 }'), 'spin')
+})
+
+test('folha construída em adoptedStyleSheets, uma só, sem repetir o mesmo nome', async () => {
+  const insertKeyframes = await freshInsertKeyframes()
+  const link = fakeSheet()
+  globalThis.document = fakeDocument({adopted: true, styleSheets: [link]})
+  globalThis.CSSStyleSheet = FakeConstructedSheet
+
+  assert.equal(insertKeyframes('a', 'from { opacity: 0 } to { opacity: 1 }'), 'a')
+  insertKeyframes('a', 'from { opacity: 0 } to { opacity: 1 }')
+  insertKeyframes('b', '100% { opacity: 0 }')
+
+  assert.equal(document.adoptedStyleSheets.length, 1)
+  assert.deepEqual(document.adoptedStyleSheets[0].rules, [
+    '@keyframes a {from { opacity: 0 } to { opacity: 1 }}',
+    '@keyframes b {100% { opacity: 0 }}'
+  ])
+  assert.deepEqual(link.rules, [])
+  assert.deepEqual(document.appended, [])
+})
+
+test('folha adotada some da lista (outro código reatribuiu): volta pra lista', async () => {
+  const insertKeyframes = await freshInsertKeyframes()
+  globalThis.document = fakeDocument({adopted: true})
+  globalThis.CSSStyleSheet = FakeConstructedSheet
+  insertKeyframes('a', '100% { opacity: 0 }')
+  const sheet = document.adoptedStyleSheets[0]
+  const other = new FakeConstructedSheet()
+  document.adoptedStyleSheets = [other]
+
+  insertKeyframes('b', '100% { opacity: 1 }')
+
+  assert.deepEqual(document.adoptedStyleSheets, [other, sheet])
+  assert.equal(sheet.rules.length, 2)
+})
+
+test('sem folha construída: insertRule numa folha do site, preferindo <link>', async () => {
+  const insertKeyframes = await freshInsertKeyframes()
+  const crossOrigin = fakeSheet({readable: false})
+  const print = fakeSheet({media: 'print'})
+  const style = fakeSheet({tagName: 'STYLE'})
+  const link = fakeSheet()
+  globalThis.document = fakeDocument({styleSheets: [crossOrigin, print, style, link], nonce: 'n'})
+
+  insertKeyframes('a', '100% { opacity: 0 }')
+  insertKeyframes('a', '100% { opacity: 0 }')
+
+  assert.deepEqual(link.rules, ['@keyframes a {100% { opacity: 0 }}'])
+  assert.deepEqual(style.rules, [])
+  assert.deepEqual(print.rules, [])
+  assert.deepEqual(document.appended, [])
+})
+
+test('sem folha construída e sem <link>: usa um <style> do site que dê pra ler', async () => {
+  const insertKeyframes = await freshInsertKeyframes()
+  const style = fakeSheet({tagName: 'STYLE'})
+  globalThis.document = fakeDocument({styleSheets: [fakeSheet({readable: false}), style]})
+
+  insertKeyframes('a', '100% { opacity: 0 }')
+
+  assert.deepEqual(style.rules, ['@keyframes a {100% { opacity: 0 }}'])
+})
+
+test('último recurso: <style> com o nonce do <meta>, uma vez por nome', async () => {
+  const insertKeyframes = await freshInsertKeyframes()
+  globalThis.document = fakeDocument({styleSheets: [fakeSheet({readable: false})], nonce: 'abc'})
+
+  insertKeyframes('a', '100% { opacity: 0 }')
+  insertKeyframes('a', '100% { opacity: 0 }')
+
+  assert.deepEqual(document.appended, [{
+    tag: 'style',
+    id: 'startlibs-keyframes-a',
+    nonce: 'abc',
+    textContent: '@keyframes a {100% { opacity: 0 }}'
+  }])
+})
+
+test('último recurso sem <meta> de nonce: <style> sem nonce', async () => {
+  const insertKeyframes = await freshInsertKeyframes()
+  globalThis.document = fakeDocument()
+
+  insertKeyframes('a', '100% { opacity: 0 }')
+
+  assert.equal('nonce' in document.appended[0], false)
+})