# API de scripts Lua do pxstud.io — Cor

> Parte da referência de scripts Lua do pxstud.io, cuja visão geral (https://pxstud.io/pt-br/docs/scripting.md) explica as convenções. Os grupos de opções e os tipos a que ela remete estão em https://pxstud.io/pt-br/docs/scripting/option-groups.md e https://pxstud.io/pt-br/docs/scripting/types.md. Tudo em um único arquivo (em inglês): https://pxstud.io/llms-full.txt. O índice de todo o site (em inglês): https://pxstud.io/llms.txt.

### Cor
Cálculos de cor sem precisar interpretar hex à mão nem misturar RGB manualmente. Cores de entrada são strings "#rrggbb" / "#rrggbbaa" ou tabelas { r, g, b, a } (0-255, a opcional); cores de saída são tabelas { r, g, b, a }, a menos que o nome indique hex. Misturar e ajustar usam OKLab por padrão, um espaço perceptual em que passos iguais parecem iguais; `space` pode ser "oklab", "oklch", "rgb" ou "hsl". Os resultados são limitados ao sRGB reduzindo o croma, então matiz e luminosidade se mantêm. Listas (ramp, shades) são geradas em uma única chamada.

#### `app.color.adjust(c, opts?)` — pura
Altera a luminosidade, o croma, o matiz, a saturação ou o alfa de uma cor, de forma absoluta ou relativa. O resultado é limitado ao gamut sRGB reduzindo o croma (luminosidade e matiz são mantidos), não cortando canais.

- `c` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.
- `opts` (table, opcional) — As chaves absolutas definem um valor; as chaves com prefixo d somam a ele (primeiro se aplica o valor definido, depois o delta). Chaves omitidas mantêm o valor da própria cor.
  - `lightness` (number) — Define a luminosidade: L do OKLab/OKLCH (0 preto - 1 branco) ou a luminosidade HSL com space = "hsl".
  - `chroma` (number ≥ 0) — Define o croma OKLCH (intensidade da cor, 0 = cinza; o sRGB chega a cerca de 0.32). Não disponível com space = "hsl".
  - `hue` (number) — Define o ângulo do matiz em graus (dá a volta em 360).
  - `saturation` (number 0–1) — Define a saturação 0-1: saturação HSL com space = "hsl"; caso contrário, o croma como fração do maior croma que o sRGB permite naquela luminosidade e matiz.
  - `alpha` (number 0–255) — Define o alfa, 0-255.
  - `dLightness` (number) — Soma à luminosidade (negativo escurece).
  - `dChroma` (number) — Soma ao croma.
  - `dHue` (number) — Gira o matiz neste número de graus.
  - `dSaturation` (number) — Soma à saturação (escala 0-1).
  - `dAlpha` (number) — Soma ao alfa (escala 0-255).
  - `space` (string; padrão "oklab") — "oklab" | "oklch" (iguais aqui) | "hsl". "rgb" não tem eixo de luminosidade nem de matiz e é rejeitado.

Retorna (table): { r, g, b, a }, cada um de 0-255.

#### `app.color.contrast(a, b)` — pura
Taxa de contraste WCAG entre duas cores (alfa ignorado), de 1 (idênticas) a 21 (preto sobre branco). 4.5 é o mínimo usual para texto legível.

- `a` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.
- `b` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.

Retorna (number): A taxa, 1-21.

#### `app.color.darken(c, amount, space?)` — pura
Atalho para app.color.adjust(c, { dLightness = -amount }).

- `c` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.
- `amount` (number) — Subtraído da luminosidade (unidades de L do OKLab, 0-1).
- `space` (string, opcional) — Onde a luminosidade é medida: "oklab" (padrão), "oklch" ou "hsl".

Retorna (table): { r, g, b, a }, cada um de 0-255.

#### `app.color.distance(a, b)` — pura
Distância euclidiana entre duas cores no OKLab (alfa ignorado). 0 = idênticas; de preto a branco é 1; cerca de 0.02 mal se percebe.

- `a` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.
- `b` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.

Retorna (number): A distância, 0 ou mais.

#### `app.color.hex(c, withAlpha?)` — pura
Uma cor como string hex em minúsculas.

- `c` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.
- `withAlpha` (boolean, opcional) — true para "#rrggbbaa"; o padrão é "#rrggbb".

Retorna (string): "#rrggbb", ou "#rrggbbaa" com withAlpha.

#### `app.color.lighten(c, amount, space?)` — pura
Atalho para app.color.adjust(c, { dLightness = amount }).

- `c` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.
- `amount` (number) — Somado à luminosidade (unidades de L do OKLab, 0-1).
- `space` (string, opcional) — Onde a luminosidade é medida: "oklab" (padrão), "oklch" ou "hsl".

Retorna (table): { r, g, b, a }, cada um de 0-255.

#### `app.color.mix(a, b, t, space?)` — pura
Mistura duas cores (inclusive o alfa) em um espaço perceptual; OKLab por padrão, o que evita os pontos médios turvos da mistura em RGB.

- `a` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.
- `b` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.
- `t` (number) — 0 = a, 1 = b; limitado a 0-1.
- `space` (string, opcional) — Espaço de interpolação: "oklab" (padrão), "oklch" (o matiz percorre o caminho mais curto), "rgb" ou "hsl".

Retorna (table): { r, g, b, a }, cada um de 0-255.

#### `app.color.nearest(c, palette)` — pura
A entrada da paleta mais próxima de c pela distância OKLab (alfa ignorado). Em caso de empate, vence a entrada anterior.

- `c` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.
- `palette` (table) — Uma lista de cores não vazia.

Retorna (number): O índice em palette, começando em 1.

#### `app.color.parse(c)` — pura
Normaliza qualquer cor aceita para { r, g, b, a } (a = 255 quando a entrada não tem alfa).

- `c` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.

Retorna (table): { r, g, b, a }, cada um de 0-255.

#### `app.color.ramp(stops, n, space?)` — pura
Um gradiente amostrado em uma lista de n cores, da primeira à última parada, com as duas extremidades incluídas. Uma única chamada, qualquer que seja n.

- `stops` (table) — Uma lista de cores, ou de { color =, pos = } com pos 0-1 (paradas sem pos são espaçadas igualmente). Precisa de pelo menos uma.
- `n` (number) — Quantas cores retornar, 1-4096. 1 retorna a primeira parada.
- `space` (string, opcional) — Espaço de interpolação: "oklab" (padrão), "oklch" (o matiz percorre o caminho mais curto), "rgb" ou "hsl".

Retorna (table): Uma lista de n cores { r, g, b, a }.

#### `app.color.shades(base, n, opts?)` — pura
Uma lista de n cores da sombra ao brilho em torno de base, para sombreamento. A base fica no índice floor(n / 2) + 1 (o meio para n ímpar) e é retornada exatamente como está. Com f indo de -1 (mais escuro) passando por 0 (base) até +1 (mais claro), o tom i tem luminosidade OKLab L + f * spread / 2 (limitada a 0-1), matiz H + f * hueShift e croma C * (1 - 0.4 * f^2), para que os extremos fiquem dentro do sRGB (o que ainda sair perde croma, nunca luminosidade). O alfa é mantido. A luminosidade é monotônica ao longo da lista.

- `base` (color) — Uma cor: "#rrggbb", "#rrggbbaa" ou { r, g, b, a }.
- `n` (number) — Quantas cores retornar, 1-4096.
- `opts` (table, opcional)
  - `spread` (number; padrão 0.5) — Faixa total de luminosidade OKLab, da sombra ao brilho (a base fica no meio: metade da faixa para baixo, metade para cima). Limitada a 0-1.
  - `hueShift` (number; padrão 8) — Graus que o matiz gira nos extremos: sombras em -hueShift, brilhos em +hueShift, reduzindo linearmente até 0 na base.

Retorna (table): Uma lista de n cores { r, g, b, a }, a mais escura primeiro.