@labpics/colors 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -72,12 +72,11 @@ export interface TranslucentRole {
72
72
  /** WCAG 2.1 ratio of the composite. */
73
73
  readonly compositeWcag: number;
74
74
  /**
75
- * `true` when the requested alpha was raised to the smallest resolvable value
76
- * (α_min) because the requested transparency is not reproducible in gamut — an
77
- * honest, flagged contract degradation (mirrors `SolvedColor.compressed` /
78
- * `GlowRole.degraded`). The colour never lies: the composite still equals the
79
- * target solid byte-for-byte; only `alpha` differs from what was asked. Always
80
- * `false` for a direct ladder emission.
75
+ * `true`, если запрошенная alpha не допускает ни одного byte-тинта,
76
+ * воспроизводящего цель в affine encoded-sRGB8 reference, и потому поднята до
77
+ * первого проходящего `binary64`. Композит остаётся побайтно равен целевому
78
+ * солиду; меняется только явно возвращённая `alpha`. У прямой лестницы всегда
79
+ * `false`.
81
80
  */
82
81
  readonly alphaCoerced: boolean;
83
82
  /**
@@ -95,24 +94,214 @@ export interface TranslucentRole {
95
94
  /** Свечение (kind glow, labui ADR-0002 §5): screen-слои + решённая интенсивность.
96
95
  * Потребитель красит слои с mix-blend-mode: screen; `vars` несёт
97
96
  * --lab-<role> (halo, oklch), --lab-<role>-core и --lab-<role>-alpha. */
98
- export interface GlowRole {
97
+ export type GlowDecisionProfileV1 = "stable-v1" | "legacy-platform-dependent-v1";
98
+ export type GlowLayerRecipeProfileV1 = "cam16-jprime-oklab-cusp-v1";
99
+ export type GlowDiagnosticProfileV1 = "cam16-ucs-jprime-li2017-v1";
100
+ export type GlowTargetStatusV1 =
101
+ | "exact-noop-unreachable"
102
+ | "legacy-reached"
103
+ | "legacy-unreachable";
104
+ export type NumericalIndeterminacyV1 =
105
+ | {
106
+ readonly reason: "sound-bound-unavailable";
107
+ readonly bounds: { readonly kind: "unavailable" };
108
+ }
109
+ | {
110
+ readonly reason: "interval-overlap";
111
+ readonly bounds: {
112
+ readonly kind: "outward";
113
+ readonly lower: number;
114
+ readonly upper: number;
115
+ };
116
+ };
117
+ export interface GlowBitExactDecisionGuaranteeV1 {
118
+ readonly kind: "bit-exact";
119
+ }
120
+ export interface GlowLegacyDecisionGuaranteeV1 {
121
+ readonly kind: "legacy-platform-dependent-v1";
122
+ }
123
+ export type GlowDecisionGuaranteeV1 =
124
+ | GlowBitExactDecisionGuaranteeV1
125
+ | GlowLegacyDecisionGuaranteeV1;
126
+
127
+ /** Поля, общие для трёх конструктивно допустимых определённых исходов Glow. */
128
+ export interface GlowDeterminateRoleBase {
99
129
  readonly kind: "glow";
100
130
  readonly cssVar: string;
101
- /** Слой пересвета (малый радиус), #RRGGBB. */
131
+ /** Core, предназначенный потребителем для меньшего blur; геометрия не моделируется. */
102
132
  readonly coreHex: string;
103
- /** Слой ореола — источник, #RRGGBB. */
133
+ /** Halo, предназначенный потребителем для большего blur; в recipe v1 это источник. */
104
134
  readonly haloHex: string;
105
135
  /** Интенсивность screen-слоя, (0, 1]. */
106
136
  readonly alpha: number;
107
- /** Фактический |ΔJ'| композита от фона. */
137
+ /** Каноническая CSS-запись той же alpha; vars использует буквально её. */
138
+ readonly alphaCss: string;
139
+ /** Exact reference-домен point-композита; не renderer/display certificate. */
140
+ readonly compositeProfile: "encoded-srgb8-screen-v1";
141
+ readonly compositeGuarantee: "bit-exact";
142
+ /** Версионированный алгоритм, построивший анатомию core/halo. */
143
+ readonly layerRecipeProfile: GlowLayerRecipeProfileV1;
144
+ /** Модель внешнего вида полного результата; обязательна, потому coreAchievedDj вычислен через CAM16. */
145
+ readonly appearanceDiagnosticProfile: GlowDiagnosticProfileV1;
146
+ /** Цель решается только по изолированному halo. */
147
+ readonly constraintLayer: "halo";
148
+ /** Запрошенный |ΔJ'| halo-композита. */
149
+ readonly targetDj: number;
150
+ /** Reference-композит изолированного halo на фоне резолва. */
151
+ readonly haloCompositeHex: string;
152
+ /** Фактический |ΔJ'| изолированного halo-композита. */
153
+ readonly haloAchievedDj: number;
154
+ /** Reference-композит изолированного core с той же alpha. */
155
+ readonly coreCompositeHex: string;
156
+ /** Фактический |ΔJ'| изолированного core-композита. */
157
+ readonly coreAchievedDj: number;
158
+ /** @deprecated Alias `haloAchievedDj` для совместимости. */
108
159
  readonly achievedDj: number;
109
- /** Цель недостижима — ближайший достижимый шаг (ADR-0002, закон 2). */
110
- readonly degraded: boolean;
111
- /** Ready-to-serve CSS value халo: "oklch(L% C H)". */
160
+ /** CSS-значение halo: `oklch(L% C H)`. */
112
161
  readonly css: string;
113
162
  }
114
163
 
115
- export type RoleResult = SolvedColor | TranslucentRole | GlowRole | NoneRole | UnreachableRole;
164
+ /** Точный no-op: выбор не вызывает CAM16 и не может достигнуть положительную цель. */
165
+ export interface GlowStableExactNoopRole extends GlowDeterminateRoleBase {
166
+ readonly decisionProfile: "stable-v1";
167
+ readonly decisionGuarantee: GlowBitExactDecisionGuaranteeV1;
168
+ readonly selectionDiagnosticProfile: null;
169
+ readonly targetStatus: "exact-noop-unreachable";
170
+ /** @deprecated Выведено из targetStatus. */
171
+ readonly degraded: true;
172
+ }
173
+
174
+ /** Legacy-выбор CAM16 достиг целевого |ΔJ'| в охарактеризованной среде исполнения. */
175
+ export interface GlowLegacyReachedRole extends GlowDeterminateRoleBase {
176
+ readonly decisionProfile: "legacy-platform-dependent-v1";
177
+ readonly decisionGuarantee: GlowLegacyDecisionGuaranteeV1;
178
+ readonly selectionDiagnosticProfile: GlowDiagnosticProfileV1;
179
+ readonly targetStatus: "legacy-reached";
180
+ /** @deprecated Выведено из targetStatus. */
181
+ readonly degraded: false;
182
+ }
183
+
184
+ /** Legacy-выбор CAM16 вернул максимум, не достигший целевого |ΔJ'|. */
185
+ export interface GlowLegacyUnreachableRole extends GlowDeterminateRoleBase {
186
+ readonly decisionProfile: "legacy-platform-dependent-v1";
187
+ readonly decisionGuarantee: GlowLegacyDecisionGuaranteeV1;
188
+ readonly selectionDiagnosticProfile: GlowDiagnosticProfileV1;
189
+ readonly targetStatus: "legacy-unreachable";
190
+ /** @deprecated Выведено из targetStatus. */
191
+ readonly degraded: true;
192
+ }
193
+
194
+ export type GlowDeterminateRole =
195
+ | GlowStableExactNoopRole
196
+ | GlowLegacyReachedRole
197
+ | GlowLegacyUnreachableRole;
198
+
199
+ /** Stable terminal outcome: no sound target/max decision, therefore no CSS vars. */
200
+ export interface GlowIndeterminateRoleBase {
201
+ readonly kind: "glow-indeterminate";
202
+ readonly cssVar: string;
203
+ readonly sourceHex: string;
204
+ readonly targetDj: number;
205
+ readonly constraintLayer: "halo";
206
+ readonly decisionProfile: "stable-v1";
207
+ readonly numericalSiteId: "glow-target-or-maximum-v1";
208
+ }
209
+
210
+ export type GlowIndeterminateRole = GlowIndeterminateRoleBase & NumericalIndeterminacyV1;
211
+
212
+ export type GlowRole = GlowDeterminateRole | GlowIndeterminateRole;
213
+
214
+ /** Численное свидетельство выбора material-alpha. Оно характеризует повторно
215
+ * проверенный результат профиля, а не строгую межплатформенную границу
216
+ * минимальной alpha. */
217
+ export interface MaterialAlphaGuaranteeBaseV1 {
218
+ /** Byte-scale affine binary64 compositor + original WCAG 2.1 (2018)
219
+ * `0.03928` EOTF, with a conservative channel envelope and both crossed seam
220
+ * sides. Platform-characterized because `powf` is not outward-bounded. */
221
+ readonly numericalProfile: "encoded-srgb-byte-scale-affine-platform-binary64-powf-v1";
222
+ }
223
+ /** Rechecked fail/pass endpoints from a fixed-step binary partition after the
224
+ * directed-search guard. No global-monotonicity, first-state or minimum claim. */
225
+ export interface MaterialBisectionBracketGuaranteeV1 extends MaterialAlphaGuaranteeBaseV1 {
226
+ readonly kind: "bisection-bracket-characterized-v1";
227
+ readonly iterations: number;
228
+ readonly lowerAlpha: number;
229
+ readonly upperAlpha: number;
230
+ }
231
+ export interface MaterialTransparentEndpointGuaranteeV1 extends MaterialAlphaGuaranteeBaseV1 {
232
+ readonly kind: "transparent-endpoint-characterized-v1";
233
+ }
234
+ export interface MaterialOpaqueEndpointGuaranteeV1 extends MaterialAlphaGuaranteeBaseV1 {
235
+ readonly kind: "opaque-endpoint-characterized-v1";
236
+ }
237
+ export type MaterialAlphaGuaranteeV1 =
238
+ | MaterialBisectionBracketGuaranteeV1
239
+ | MaterialTransparentEndpointGuaranteeV1
240
+ | MaterialOpaqueEndpointGuaranteeV1;
241
+
242
+ /** Двухслойный материал (kind material, #89): тинт `01` (с выведенной α) над
243
+ * опаковой базой `02`, обе — один тон. `vars` несёт --lab-<role> (солид-канон,
244
+ * опаковый), --lab-<role>-01 (тинт oklch/α) и --lab-<role>-02 (база, опаковая).
245
+ * Композит-гарантия читаемости пересчитываема из toneHex/alpha (α-граница). */
246
+ export interface MaterialRoleBase {
247
+ readonly kind: "material";
248
+ readonly cssVar: string;
249
+ /** Тон #RRGGBB: тинт 01, база 02 и солид-канон одновременно (равны). */
250
+ readonly toneHex: string;
251
+ /** Худший WCAG-контраст коммит-полюса по коридору [чёрный, белый]. */
252
+ readonly worstContrast: number;
253
+ /** Запрошенный WCAG-пол (4.5 / 3.0); держится только при `alphaStatus: "satisfied"`. */
254
+ readonly floor: number;
255
+ /** Коммит-полюс поверхности белый (true, тёмный тон) или чёрный (false). */
256
+ readonly poleWhite: boolean;
257
+ /** Фактический |ΔJ'| тона-базы от фона — различимость поверхности. */
258
+ readonly achievedDj: number;
259
+ /** Целевой |ΔJ'| тона был недостижим — ближайший достижимый (ADR-0002). */
260
+ readonly toneCompressed: boolean;
261
+ /** Оттенок семьи выродился у края гамута (честный флаг; false у нейтрали). */
262
+ readonly hueVanished: boolean;
263
+ /** Солид-канон отличим от фона резолва на 8-битной сетке. */
264
+ readonly distinct: boolean;
265
+ /** Ready-to-serve CSS value солид-канона: "oklch(L% C H)". */
266
+ readonly css: string;
267
+ }
268
+
269
+ /** Уже прозрачная граничная точка держит запрошенный пол. */
270
+ export interface MaterialSatisfiedTransparentRole extends MaterialRoleBase {
271
+ readonly alpha: 0;
272
+ readonly alphaGuarantee: MaterialTransparentEndpointGuaranteeV1;
273
+ readonly alphaStatus: "satisfied";
274
+ readonly guaranteed: true;
275
+ }
276
+
277
+ /** Повторно проверенная верхняя граница интервала держит запрошенный пол. */
278
+ export interface MaterialSatisfiedBracketRole extends MaterialRoleBase {
279
+ readonly alpha: number;
280
+ readonly alphaGuarantee: MaterialBisectionBracketGuaranteeV1;
281
+ readonly alphaStatus: "satisfied";
282
+ readonly guaranteed: true;
283
+ }
284
+
285
+ /** Даже непрозрачная граничная точка не держит запрошенный пол; возвращается alpha 1. */
286
+ export interface MaterialDegradedOpaqueRole extends MaterialRoleBase {
287
+ readonly alpha: 1;
288
+ readonly alphaGuarantee: MaterialOpaqueEndpointGuaranteeV1;
289
+ readonly alphaStatus: "degraded";
290
+ readonly guaranteed: false;
291
+ }
292
+
293
+ export type MaterialRole =
294
+ | MaterialSatisfiedTransparentRole
295
+ | MaterialSatisfiedBracketRole
296
+ | MaterialDegradedOpaqueRole;
297
+
298
+ export type RoleResult =
299
+ | SolvedColor
300
+ | TranslucentRole
301
+ | GlowRole
302
+ | MaterialRole
303
+ | NoneRole
304
+ | UnreachableRole;
116
305
 
117
306
  /** Пер-темная четвёрка якорных hex (light / dark / light-ic / dark-ic). */
118
307
  export interface ThemeAnchors {
@@ -129,16 +318,60 @@ export type LadderSource =
129
318
  | { kind: "sentiment"; name: string }
130
319
  | { kind: "neutral"; pick: "mid" | "edge" | "inverted" | "light" | "dark" };
131
320
 
321
+ /** Closed physical ladder menu accepted by the config compiler. */
322
+ export type LadderPositionV1 =
323
+ | "label-primary"
324
+ | "label-secondary"
325
+ | "label-tertiary"
326
+ | "label-quaternary"
327
+ | "fill-primary"
328
+ | "fill-secondary"
329
+ | "fill-tertiary"
330
+ | "fill-quaternary"
331
+ | "border-base"
332
+ | "border-soft"
333
+ | "border-strong"
334
+ | "focus-ring"
335
+ | "glow"
336
+ | "skeleton-base"
337
+ | "skeleton-highlight"
338
+ | "neutral-fill-primary"
339
+ | "neutral-fill-secondary"
340
+ | "neutral-fill-tertiary"
341
+ | "neutral-fill-quaternary"
342
+ | "neutral-border-base"
343
+ | "neutral-border-soft"
344
+ | "shadow-minor"
345
+ | "shadow-ambient"
346
+ | "shadow-penumbra"
347
+ | "shadow-major";
348
+
132
349
  /** Рецепт роли из физического меню движка. */
133
350
  export type RoleRecipe =
134
- | { kind: "text-anchor"; fraction: number; floor: "aa-text" | "aa-ui" | "none" }
351
+ | {
352
+ kind: "text-anchor";
353
+ fraction: number;
354
+ floor: "aa-text" | "aa-ui" | "none";
355
+ hue?: LadderSource;
356
+ }
135
357
  | { kind: "dj-anchor"; light: number; dark: number }
136
358
  | { kind: "decorative-lc"; magnitude: number }
137
- | { kind: "ladder"; source: LadderSource; position: string }
138
- | { kind: "glow"; source: LadderSource; step: "subtle" | "base" | "bloom" }
359
+ | {
360
+ kind: "ladder";
361
+ source: LadderSource;
362
+ position: LadderPositionV1;
363
+ floor?: "aa-text" | "aa-ui" | "none";
364
+ }
365
+ | {
366
+ kind: "glow";
367
+ source: LadderSource;
368
+ step: "subtle" | "base" | "bloom";
369
+ decision_profile: GlowDecisionProfileV1;
370
+ }
139
371
  | { kind: "pair-fill"; source: LadderSource }
140
372
  | { kind: "pair-label"; source: LadderSource; fraction: number; floor: "aa-text" | "aa-ui" | "none" }
141
373
  | { kind: "alpha-analog"; of: LadderSource; alpha: number }
374
+ | { kind: "material"; source: LadderSource; tone_light: number; tone_dark: number; floor: "aa-text" | "aa-ui" }
142
375
  | { kind: "zero" };
143
376
 
144
377
  /** Полный конфиг дизайн-системы клиента — вход loadConfig (JSON.stringify(config)). */
@@ -169,7 +402,7 @@ export interface ThemeConfig {
169
402
  readonly themes: ReadonlyArray<{ name: string; preset: "srgb" | "dim" | "srgb-ic" | "dim-ic" }>;
170
403
  /** Словарь ролей дизайн-системы. Конфиг обязан нести собственные роли; пустой
171
404
  * контракт (без `roles` и `aliases`) отклоняется на загрузке. */
172
- readonly roles?: ReadonlyArray<{ name: string; recipe: RoleRecipe }>;
405
+ readonly roles: ReadonlyArray<{ name: string; recipe: RoleRecipe }>;
173
406
  readonly aliases?: ReadonlyArray<{ alias: string; target: string }>;
174
407
  }
175
408
 
@@ -204,6 +437,14 @@ export interface ResolvedTheme {
204
437
  export class LabColors {
205
438
  free(): void;
206
439
  [Symbol.dispose](): void;
440
+ /**
441
+ * Exact stable-Glow runtime recheck. Returns whether the point screen
442
+ * layer is a byte-for-byte no-op for every alpha under encoded sRGB8.
443
+ * `adaptTheme` uses this cheap core-owned predicate to detect the only
444
+ * stable determinate/indeterminate class transition without running CAM16
445
+ * or re-solving on every animated-background frame.
446
+ */
447
+ isStableGlowPointNoop(tint_hex: string, bg_hex: string): boolean;
207
448
  /**
208
449
  * Загрузить конфиг дизайн-системы (JSON по типу `ThemeConfig` из `.d.ts`).
209
450
  *
@@ -216,7 +457,12 @@ export class LabColors {
216
457
  */
217
458
  loadConfig(json: string): string;
218
459
  /**
219
- * Calculate the muddiness score (0 to 1) of an sRGB hex colour.
460
+ * Return the frozen legacy `muddiness` coordinate for an sRGB hex colour.
461
+ *
462
+ * This is an experimental compatibility proxy: it reproduces the historic
463
+ * numeric API, but is not an observer-validated human clean/dirty verdict
464
+ * or a production decision. The legacy identifier is retained only for
465
+ * compatibility.
220
466
  */
221
467
  muddiness(hex: string): number;
222
468
  /**
@@ -261,9 +507,9 @@ export class LabColors {
261
507
  * Returns a `ResolvedTheme` object. Per-role unreachability is part of a
262
508
  * successful result (each role carries its own `kind`); only whole-call
263
509
  * failures reject (no config loaded yet as `config_required`, invalid hex,
264
- * unknown theme, and the by-construction-unreachable oklch serialisation
265
- * failure as `internal_error`) — as a structured `"<code>: <message>"`
266
- * error, never an unwound panic.
510
+ * unknown theme, a core invariant failure, and the by-construction-
511
+ * unreachable oklch serialisation failure as `internal_error`) — as a
512
+ * structured `"<code>: <message>"` error, never an unwound panic.
267
513
  */
268
514
  resolveTheme(bg_hex: string, theme: string): ResolvedTheme;
269
515
  }
@@ -273,6 +519,7 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
273
519
  export interface InitOutput {
274
520
  readonly memory: WebAssembly.Memory;
275
521
  readonly __wbg_labcolors_free: (a: number, b: number) => void;
522
+ readonly labcolors_isStableGlowPointNoop: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
276
523
  readonly labcolors_loadConfig: (a: number, b: number, c: number, d: number) => void;
277
524
  readonly labcolors_muddiness: (a: number, b: number, c: number, d: number) => void;
278
525
  readonly labcolors_new: () => number;
package/pkg/labcolors.js CHANGED
@@ -17,6 +17,35 @@ export class LabColors {
17
17
  const ptr = this.__destroy_into_raw();
18
18
  wasm.__wbg_labcolors_free(ptr, 0);
19
19
  }
20
+ /**
21
+ * Exact stable-Glow runtime recheck. Returns whether the point screen
22
+ * layer is a byte-for-byte no-op for every alpha under encoded sRGB8.
23
+ * `adaptTheme` uses this cheap core-owned predicate to detect the only
24
+ * stable determinate/indeterminate class transition without running CAM16
25
+ * or re-solving on every animated-background frame.
26
+ * @param {string} tint_hex
27
+ * @param {string} bg_hex
28
+ * @returns {boolean}
29
+ */
30
+ isStableGlowPointNoop(tint_hex, bg_hex) {
31
+ try {
32
+ const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
33
+ const ptr0 = passStringToWasm0(tint_hex, wasm.__wbindgen_export, wasm.__wbindgen_export2);
34
+ const len0 = WASM_VECTOR_LEN;
35
+ const ptr1 = passStringToWasm0(bg_hex, wasm.__wbindgen_export, wasm.__wbindgen_export2);
36
+ const len1 = WASM_VECTOR_LEN;
37
+ wasm.labcolors_isStableGlowPointNoop(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1);
38
+ var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
39
+ var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
40
+ var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
41
+ if (r2) {
42
+ throw takeObject(r1);
43
+ }
44
+ return r0 !== 0;
45
+ } finally {
46
+ wasm.__wbindgen_add_to_stack_pointer(16);
47
+ }
48
+ }
20
49
  /**
21
50
  * Загрузить конфиг дизайн-системы (JSON по типу `ThemeConfig` из `.d.ts`).
22
51
  *
@@ -56,7 +85,12 @@ export class LabColors {
56
85
  }
57
86
  }
58
87
  /**
59
- * Calculate the muddiness score (0 to 1) of an sRGB hex colour.
88
+ * Return the frozen legacy `muddiness` coordinate for an sRGB hex colour.
89
+ *
90
+ * This is an experimental compatibility proxy: it reproduces the historic
91
+ * numeric API, but is not an observer-validated human clean/dirty verdict
92
+ * or a production decision. The legacy identifier is retained only for
93
+ * compatibility.
60
94
  * @param {string} hex
61
95
  * @returns {number}
62
96
  */
@@ -178,9 +212,9 @@ export class LabColors {
178
212
  * Returns a `ResolvedTheme` object. Per-role unreachability is part of a
179
213
  * successful result (each role carries its own `kind`); only whole-call
180
214
  * failures reject (no config loaded yet as `config_required`, invalid hex,
181
- * unknown theme, and the by-construction-unreachable oklch serialisation
182
- * failure as `internal_error`) — as a structured `"<code>: <message>"`
183
- * error, never an unwound panic.
215
+ * unknown theme, a core invariant failure, and the by-construction-
216
+ * unreachable oklch serialisation failure as `internal_error`) — as a
217
+ * structured `"<code>: <message>"` error, never an unwound panic.
184
218
  * @param {string} bg_hex
185
219
  * @param {string} theme
186
220
  * @returns {ResolvedTheme}
Binary file
@@ -2,6 +2,7 @@
2
2
  /* eslint-disable */
3
3
  export const memory: WebAssembly.Memory;
4
4
  export const __wbg_labcolors_free: (a: number, b: number) => void;
5
+ export const labcolors_isStableGlowPointNoop: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
5
6
  export const labcolors_loadConfig: (a: number, b: number, c: number, d: number) => void;
6
7
  export const labcolors_muddiness: (a: number, b: number, c: number, d: number) => void;
7
8
  export const labcolors_new: () => number;