@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.
package/adapt-theme.js CHANGED
@@ -39,13 +39,11 @@
39
39
  // usually sit on a substrate, so a brief dip of the aesthetic *surplus*
40
40
  // during the ease is imperceptible while the freshly-solved destination is
41
41
  // always legal.
42
- // * Strict (`strict: true`): the WCAG legal floor is HELD every frame. For
43
- // text directly on animated content or under `prefers-contrast`, an
44
- // intermediate colour is only shown while it still clears the role's
45
- // `legalFloor` against the live background; a role whose eased intermediate
46
- // would dip below its floor is advanced (monotonically) to the least blend
47
- // that stays legal — never below the line, never a backwards flicker. Roles
48
- // with no legal floor (decorative) ease freely either way.
42
+ // * Strict (`strict: true`): requests the legacy per-frame floor clamp. The
43
+ // current Oklab→clip→sRGB8 path is characterized, but is not globally
44
+ // monotone and therefore does not prove a least/legal blend for every frame;
45
+ // #287 owns the finite hard-floor-safe replacement. Roles with no declared
46
+ // floor (decorative) ease freely either way.
49
47
 
50
48
  import { applyTheme } from "./apply-theme.js";
51
49
  import {
@@ -67,9 +65,9 @@ function easeOut(t) {
67
65
  return 1 - u * u * u;
68
66
  }
69
67
 
70
- /** WCAG 2.1 relative luminance of `#RRGGBB` — a faithful transcription of the
71
- * normative definition (0.03928 split, 2.4 exponent), so the strict floor-clamp
72
- * agrees byte-for-byte with the core's `legalFloor` semantics. */
68
+ /** Relative luminance of `#RRGGBB` in the frozen original WCAG 2.1 (2018)
69
+ * profile (0.03928 split, 2.4 exponent), so the strict floor-clamp agrees
70
+ * byte-for-byte with the core's versioned `legalFloor` semantics. */
73
71
  function relativeLuminanceHex(hex) {
74
72
  const rgb = parseCssColor(hex) ?? [0, 0, 0, 1];
75
73
  const lin = (c) => {
@@ -123,7 +121,7 @@ function segLum(seg, t) {
123
121
  *
124
122
  * @param {*} element
125
123
  * @param {object} options
126
- * @param {{ resolveTheme: (bg:string,theme:string)=>any, recheckContrast:(bg:string,fgs:string[],theme:string)=>ArrayLike<number> }} options.colors
124
+ * @param {{ resolveTheme: (bg:string,theme:string)=>any, recheckContrast:(bg:string,fgs:string[],theme:string)=>ArrayLike<number>, isStableGlowPointNoop?:(tint:string,bg:string)=>boolean }} options.colors
127
125
  * @param {string} options.theme
128
126
  * @param {string | string[] | (() => string | string[])} [options.background]
129
127
  * explicit effective background. An ARRAY (or a function returning one) is a
@@ -136,8 +134,9 @@ function segLum(seg, t) {
136
134
  * @param {number} [options.sustainMs=120] breach must persist this long
137
135
  * @param {number} [options.dwellMs=250] minimum between re-solves
138
136
  * @param {number} [options.easeMs=280] crossfade duration
139
- * @param {boolean} [options.strict=false] hold each role's WCAG legal floor
140
- * every frame of the ease (for text on animated content / `prefers-contrast`)
137
+ * @param {boolean} [options.strict=false] enable the legacy characterized
138
+ * per-frame clamp; the current non-monotone interpolation path is not a
139
+ * universal floor certificate (replacement tracked by #287)
141
140
  * @param {boolean} [options.reducedMotion] override; default reads matchMedia
142
141
  * @param {() => number} [options.now] clock (default performance.now/Date.now)
143
142
  * @param {*} [options.win=globalThis]
@@ -171,6 +170,11 @@ export function adaptTheme(element, options) {
171
170
  let theme = options.theme;
172
171
  /** @type {{ cssVar: string, key: string, lc: number, hex: string, legalFloor: number|null }[]} stable role order */
173
172
  let roles = [];
173
+ /** Stable Glow roles need an exact class recheck in addition to color
174
+ * contrast rechecks. The only determinate stable state is the core-certified
175
+ * quantised screen point no-op; every other state is typed Indeterminate and must have
176
+ * no halo/core/alpha vars. */
177
+ let stableGlows = [];
174
178
  /** Full canonical var set from the last solve — the `result.vars` of EVERY
175
179
  * reachable role (color AND translucent), each an oklch string. Every apply is
176
180
  * `applyTheme(target, {...baseVars, ...easedColorOverlay})`, so translucent
@@ -254,9 +258,109 @@ export function adaptTheme(element, options) {
254
258
  return { breached, worstIdx };
255
259
  };
256
260
 
257
- // Resolve a fresh set and adopt it as the current colours (no ease).
258
- const solveAndAdopt = (bg, now) => {
259
- const result = colors.resolveTheme(bg, theme);
261
+ const stableVarKeys = (role) => [
262
+ role.cssVar,
263
+ `${role.cssVar}-core`,
264
+ `${role.cssVar}-alpha`,
265
+ ];
266
+
267
+ const hasDeterminateGlowEnvelope = (result, role, emittedKeys) =>
268
+ role.compositeProfile === "encoded-srgb8-screen-v1" &&
269
+ role.compositeGuarantee === "bit-exact" &&
270
+ role.layerRecipeProfile === "cam16-jprime-oklab-cusp-v1" &&
271
+ role.appearanceDiagnosticProfile === "cam16-ucs-jprime-li2017-v1" &&
272
+ role.constraintLayer === "halo" &&
273
+ typeof role.coreHex === "string" &&
274
+ typeof role.haloHex === "string" &&
275
+ emittedKeys.every((emittedKey) => typeof result.vars?.[emittedKey] === "string");
276
+
277
+ const validatedStableGlowsFrom = (result) => {
278
+ const out = [];
279
+ for (const [key, role] of Object.entries(result.roles ?? {})) {
280
+ if (!role) continue;
281
+ const isGlow = role.kind === "glow" || role.kind === "glow-indeterminate";
282
+ if (!isGlow) {
283
+ if (role.decisionProfile !== undefined) {
284
+ throw new TypeError(`adaptTheme: decision profile on non-Glow role '${key}'`);
285
+ }
286
+ continue;
287
+ }
288
+ const expectedCssVar = `--lab-${key}`;
289
+ if (role.cssVar !== expectedCssVar) {
290
+ throw new TypeError(
291
+ `adaptTheme: Glow '${key}' has non-canonical cssVar`,
292
+ );
293
+ }
294
+ const emittedKeys = stableVarKeys(role);
295
+ if (role.decisionProfile === "legacy-platform-dependent-v1") {
296
+ if (role.kind !== "glow") {
297
+ throw new TypeError(
298
+ `adaptTheme: legacy Glow '${key}' cannot be Indeterminate`,
299
+ );
300
+ }
301
+ const reached =
302
+ role.targetStatus === "legacy-reached" && role.degraded === false;
303
+ const unreachable =
304
+ role.targetStatus === "legacy-unreachable" && role.degraded === true;
305
+ if (
306
+ !hasDeterminateGlowEnvelope(result, role, emittedKeys) ||
307
+ role.decisionGuarantee?.kind !== "legacy-platform-dependent-v1" ||
308
+ role.selectionDiagnosticProfile !== "cam16-ucs-jprime-li2017-v1" ||
309
+ (!reached && !unreachable)
310
+ ) {
311
+ throw new TypeError(
312
+ `adaptTheme: legacy Glow '${key}' lacks lawful legacy evidence`,
313
+ );
314
+ }
315
+ continue;
316
+ }
317
+ if (role.decisionProfile !== "stable-v1") {
318
+ throw new TypeError(`adaptTheme: Glow '${key}' lacks an explicit known decisionProfile`);
319
+ }
320
+ if (role.kind === "glow") {
321
+ if (
322
+ role.decisionGuarantee?.kind !== "bit-exact" ||
323
+ !hasDeterminateGlowEnvelope(result, role, emittedKeys) ||
324
+ role.selectionDiagnosticProfile !== null ||
325
+ role.targetStatus !== "exact-noop-unreachable" ||
326
+ role.degraded !== true
327
+ ) {
328
+ throw new TypeError(`adaptTheme: stable Glow '${key}' lacks BitExact evidence`);
329
+ }
330
+ out.push({ key, cssVar: role.cssVar, sourceHex: role.haloHex, indeterminate: false });
331
+ continue;
332
+ }
333
+ if (role.kind === "glow-indeterminate") {
334
+ const expectedSite =
335
+ role.numericalSiteId === "glow-target-or-maximum-v1" &&
336
+ role.constraintLayer === "halo";
337
+ const unavailable =
338
+ role.reason === "sound-bound-unavailable" && role.bounds?.kind === "unavailable";
339
+ const soundOverlap =
340
+ role.reason === "interval-overlap" &&
341
+ role.bounds?.kind === "outward" &&
342
+ Number.isFinite(role.bounds.lower) &&
343
+ Number.isFinite(role.bounds.upper) &&
344
+ role.bounds.lower <= role.bounds.upper;
345
+ const lawfulEvidence = expectedSite && (unavailable || soundOverlap);
346
+ if (
347
+ !lawfulEvidence ||
348
+ typeof role.sourceHex !== "string" ||
349
+ emittedKeys.some((emittedKey) => Object.hasOwn(result.vars ?? {}, emittedKey))
350
+ ) {
351
+ throw new TypeError(`adaptTheme: stable Glow '${key}' lacks lawful Indeterminate evidence`);
352
+ }
353
+ out.push({ key, cssVar: role.cssVar, sourceHex: role.sourceHex, indeterminate: true });
354
+ continue;
355
+ }
356
+ throw new TypeError(`adaptTheme: stable decision profile on unknown Glow role '${key}'`);
357
+ }
358
+ return out;
359
+ };
360
+
361
+ // Adopt one already-resolved set as the current colours (no ease).
362
+ const adoptResolved = (result, now) => {
363
+ const nextStableGlows = validatedStableGlowsFrom(result);
260
364
  // Carry the FULL canonical var set (color + translucent) so no reachable
261
365
  // role is dropped by a subsequent apply; only color roles feed the ease.
262
366
  baseVars = result.vars && typeof result.vars === "object" ? result.vars : {};
@@ -269,6 +373,7 @@ export function adaptTheme(element, options) {
269
373
  hex: r.hex,
270
374
  legalFloor: typeof r.legalFloor === "number" ? r.legalFloor : null,
271
375
  }));
376
+ stableGlows = nextStableGlows;
272
377
  fgsCache = roles.map((r) => r.hex);
273
378
  // The adopt may change the var/role KEY SET — force the next write through
274
379
  // `applyTheme`'s full clear-then-write instead of the mid-ease diff path.
@@ -278,6 +383,9 @@ export function adaptTheme(element, options) {
278
383
  return result;
279
384
  };
280
385
 
386
+ // Resolve a fresh set and adopt it as the current colours (no ease).
387
+ const solveAndAdopt = (bg, now) => adoptResolved(colors.resolveTheme(bg, theme), now);
388
+
281
389
  // Solve+adopt against the hardest of `samples`. With one sample this is a
282
390
  // single solve; with several it does a provisional solve to learn the role
283
391
  // colours, picks the worst sample for them, and re-solves against it if that
@@ -328,6 +436,91 @@ export function adaptTheme(element, options) {
328
436
  // oklch form, translucent roles their tint+alpha.
329
437
  const applyRolesDirect = () => applyHexes({});
330
438
 
439
+ /**
440
+ * Recheck the background-dependent stable Glow decision class. This is not a
441
+ * contrast surplus and therefore never passes through sustain/dwell/easing.
442
+ * A stable Glow result requires the core-owned exact predicate. Missing
443
+ * capability is a typed integration error, never a hidden full-solve loop.
444
+ */
445
+ const reconcileStableGlows = (samples) => {
446
+ if (stableGlows.length === 0) return false;
447
+
448
+ if (typeof colors.isStableGlowPointNoop !== "function") {
449
+ throw new TypeError(
450
+ "adaptTheme: stable Glow requires colors.isStableGlowPointNoop",
451
+ );
452
+ }
453
+ const desired = new Map();
454
+ for (const role of stableGlows) {
455
+ desired.set(
456
+ role.key,
457
+ samples.some((bg) => !colors.isStableGlowPointNoop(role.sourceHex, bg)),
458
+ );
459
+ }
460
+
461
+ const changed = stableGlows.some(
462
+ (role) => desired.get(role.key) !== role.indeterminate,
463
+ );
464
+ if (!changed) return false;
465
+
466
+ // Re-resolve exactly once to refresh certificates/source metadata. Only
467
+ // stable Glow satellites are adopted; color/translucent roles remain under
468
+ // the existing adaptive contrast controller and do not snap.
469
+ const fresh = colors.resolveTheme(samples[0], theme);
470
+ const freshStable = validatedStableGlowsFrom(fresh);
471
+ const freshByKey = new Map(freshStable.map((role) => [role.key, role]));
472
+ const nextVars = { ...baseVars };
473
+ for (const previous of stableGlows) {
474
+ const current = freshByKey.get(previous.key);
475
+ if (!current) {
476
+ throw new TypeError(`adaptTheme: stable Glow role '${previous.key}' disappeared`);
477
+ }
478
+ for (const key of stableVarKeys(previous)) delete nextVars[key];
479
+ const indeterminate = desired.get(previous.key);
480
+ if (!indeterminate) {
481
+ for (const key of stableVarKeys(current)) {
482
+ if (typeof fresh.vars?.[key] !== "string") {
483
+ throw new TypeError(
484
+ `adaptTheme: determinate stable Glow '${previous.key}' lacks '${key}'`,
485
+ );
486
+ }
487
+ nextVars[key] = fresh.vars[key];
488
+ }
489
+ }
490
+ current.indeterminate = indeterminate;
491
+ }
492
+
493
+ const previousVars = baseVars;
494
+ baseVars = nextVars;
495
+ stableGlows = freshStable.map((role) => {
496
+ const state = desired.get(role.key);
497
+ return state === undefined ? role : { ...role, indeterminate: state };
498
+ });
499
+ if (written !== null) {
500
+ // A stable certificate transition may coincide with an in-flight color
501
+ // ease. Patch only Glow satellites so the already-painted color overlay
502
+ // remains continuous; resetting `written`/`easing` here would snap every
503
+ // color role to its canonical destination.
504
+ const nextWritten = { ...written };
505
+ const stableKeys = new Set(
506
+ stableGlows.flatMap((role) => stableVarKeys(role)),
507
+ );
508
+ for (const key of stableKeys) {
509
+ if (typeof nextVars[key] === "string") {
510
+ if (previousVars[key] !== nextVars[key] || written[key] !== nextVars[key]) {
511
+ target.style.setProperty(key, nextVars[key]);
512
+ }
513
+ nextWritten[key] = nextVars[key];
514
+ } else {
515
+ target.style.removeProperty(key);
516
+ delete nextWritten[key];
517
+ }
518
+ }
519
+ written = nextWritten;
520
+ }
521
+ return true;
522
+ };
523
+
331
524
  // Begin an ease from the currently-applied colours toward the role colours.
332
525
  // `held` latches the per-role displayed blend so it only ever advances toward
333
526
  // the destination (strict mode) — see `stepEase`.
@@ -343,15 +536,12 @@ export function adaptTheme(element, options) {
343
536
  if (easing.size === 0) applyRolesDirect();
344
537
  };
345
538
 
346
- // Strict mode: the least blend in [e, 1] whose interpolated colour clears
347
- // `floor` against EVERY background sample in `bgLums`. The destination (`to`,
348
- // blend 1) is a freshly-solved legal colour, so it anchors the search; we
349
- // bisect toward it from the natural ease value `e`. Returns `e` unchanged when
350
- // the eased colour is already legal everywhere (the common case — no
351
- // intervention). The returned blend is always floor-legal against the worst
352
- // sample, except in the unavoidable case where even `to` is illegal against a
353
- // sample that drifted further this frame — then it returns 1 (the most-legal
354
- // colour we have) and the recheck loop re-solves.
539
+ // Legacy strict clamp: fixed-step bisection from the natural ease value `e`
540
+ // toward the freshly-solved destination. Oklab→clip→sRGB8 legality is not
541
+ // globally monotone, so this is a characterized compatibility selector, not
542
+ // a proof of the least or universally legal blend. #287 owns the finite
543
+ // hard-floor-safe replacement. If even `to` fails after background drift, the
544
+ // selector returns 1 and the recheck loop requests another solve.
355
545
  const floorBlend = (seg, e, bgLums, floor) => {
356
546
  const legalAt = (blend) => {
357
547
  const lum = segLum(seg, blend);
@@ -418,8 +608,9 @@ export function adaptTheme(element, options) {
418
608
  // so on a frame where they drift favourably it could return a *lower*
419
609
  // blend than last frame — a backwards step toward the old colour, the
420
610
  // precise jarring reversal this mode exists to avoid. `held` clamps that
421
- // out: the colour progresses monotonically from→to and never below the
422
- // legal line on any sample.
611
+ // out: the scalar blend parameter never retreats. This latch alone is
612
+ // not a proof that the quantized colour stays above every floor; #287
613
+ // owns that finite-path guarantee.
423
614
  blend = Math.max(floorBlend(seg, e, bgLums, r.legalFloor), seg.held);
424
615
  seg.held = blend;
425
616
  }
@@ -471,8 +662,9 @@ export function adaptTheme(element, options) {
471
662
  const now = nowArg ?? clock();
472
663
  const samples = readSamples();
473
664
  const key = samples.join("|");
474
- // Advance any in-flight ease first (against the live samples, so strict mode
475
- // holds the legal floor every frame as the backdrop keeps drifting under it).
665
+ // Advance any in-flight ease first against the live samples. Legacy strict
666
+ // mode applies its characterized clamp here; it is not a universal
667
+ // per-frame floor certificate (#287).
476
668
  if (easing.size > 0) stepEase(now, samples, key);
477
669
 
478
670
  // Steady state: a static backdrop with no in-flight ease and no pending
@@ -480,6 +672,7 @@ export function adaptTheme(element, options) {
480
672
  // backdrop, so the sustain timer can fire on one that changed once to a
481
673
  // failing value and then held.
482
674
  if (key === lastKey && easing.size === 0 && breachSince === null) return;
675
+ if (key !== lastKey) reconcileStableGlows(samples);
483
676
  lastKey = key;
484
677
  if (roles.length === 0) return;
485
678
 
@@ -501,6 +694,7 @@ export function adaptTheme(element, options) {
501
694
  // reintroducing flicker when a re-solve overlaps a previous ease.
502
695
  const fromByVar = paintedNow(now, samples, key);
503
696
  solveAndAdopt(samples[worstIdx], now);
697
+ reconcileStableGlows(samples);
504
698
  beginEase(fromByVar, now);
505
699
  stepEase(now, samples, key);
506
700
  };
@@ -516,6 +710,7 @@ export function adaptTheme(element, options) {
516
710
  const samples = readSamples();
517
711
  lastKey = samples.join("|");
518
712
  solveAndAdoptWorst(samples, clock());
713
+ reconcileStableGlows(samples);
519
714
  applyRolesDirect();
520
715
  }
521
716
 
@@ -527,6 +722,7 @@ export function adaptTheme(element, options) {
527
722
  lastKey = samples.join("|");
528
723
  easing = new Map();
529
724
  solveAndAdoptWorst(samples, clock());
725
+ reconcileStableGlows(samples);
530
726
  applyRolesDirect(); // instant — a theme switch is intent, not drift
531
727
  },
532
728
  start() {
package/apply-theme.js CHANGED
@@ -12,10 +12,11 @@ const LAB_VAR_PREFIX = "--lab-";
12
12
  *
13
13
  * First clears every inline `--lab-*` custom property a previous call set on
14
14
  * this element, then writes every reachable role from `result.vars` via
15
- * `setProperty`. Unreachable and zero-token (`none`) roles carry no colour, so
16
- * they are absent from `vars` and are not written — the caller's CSS fallbacks
17
- * stay in effect for those, including across theme re-application (a role
18
- * reachable in the previous theme but not in the new one does not linger).
15
+ * `setProperty`. Unreachable, zero-token (`none`), and stable
16
+ * `glow-indeterminate` roles carry no selected CSS value, so they are absent
17
+ * from `vars` and are not written — the caller's CSS fallbacks stay in effect
18
+ * for those, including across theme re-application (a role reachable in the
19
+ * previous theme but not in the new one does not linger).
19
20
  *
20
21
  * @param {HTMLElement} element - The target element (e.g. `document.documentElement`).
21
22
  * @param {{ vars: Record<string, string> }} result - A `resolveTheme(...)` result.
@@ -0,0 +1,19 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "package": {
4
+ "name": "@labpics/colors",
5
+ "version": "0.10.0"
6
+ },
7
+ "sourceSha": "52d7895774c2fa3796e51f7133452cf83c09346b",
8
+ "coreVersion": "0.2.0",
9
+ "conformance": {
10
+ "packVersion": "2.0.0",
11
+ "packDigest": "64a68cbd",
12
+ "manifestSha256": "765c254d37fb4108461bbe71f392bc5ec42eca84ae58cc1cbf2562af6768ae1f",
13
+ "familySetSha256": "1b7b446a66f1bf57a7d0538c4cb94b78d8ec7bdd42f7973a09c0029724deaa62"
14
+ },
15
+ "wasm": {
16
+ "bytes": 371584,
17
+ "sha256": "44b0015851b120bee249e87fba9cbae6465d477ce333db4478f1a4ddc0cccb2c"
18
+ }
19
+ }
package/effective-bg.d.ts CHANGED
@@ -41,8 +41,9 @@ export declare function oklabLerp(from: string, to: string, t: number): string;
41
41
  export declare function compositeStackToHex(layersFrontToBack: Rgba[], opaqueBase: Rgba): string;
42
42
 
43
43
  /**
44
- * The opaque effective background `#RRGGBB` visible behind `element`'s content,
45
- * by walking ancestors and alpha-compositing their `background-color`s.
44
+ * Legacy opaque reference-background estimate for the supported
45
+ * `background-color` subset. This is not a browser pixel observation; use an
46
+ * explicit sampled background when correctness depends on unsupported layers.
46
47
  */
47
48
  export declare function effectiveBackground(
48
49
  element: unknown,
package/effective-bg.js CHANGED
@@ -3,13 +3,14 @@
3
3
  // `labcolors` resolves roles against a *solid* background. A real UI surface is
4
4
  // often translucent (a panel at `rgba(…, .8)` over its parents) or has no
5
5
  // background of its own (inheriting whatever is behind it). To resolve such a
6
- // surface honestly you need the **effective** background: the opaque colour a
7
- // viewer actually sees behind the element's own content.
6
+ // surface you need a background observation. This legacy helper produces a
7
+ // reference estimate for the subset it understands; it is not a browser pixel
8
+ // capture or a claim about what a viewer actually sees.
8
9
  //
9
10
  // This module computes it by walking the ancestor chain and **alpha-compositing**
10
11
  // each element's `background-color` (front-to-back) until the stack is opaque,
11
- // over an opaque fallback (white by default). It is the bridge from the DOM's
12
- // layered, translucent reality to the single solid hex the WASM core consumes.
12
+ // over an opaque fallback (white by default), yielding one solid reference hex
13
+ // the WASM core can consume.
13
14
  //
14
15
  // HONEST LIMIT: this composites solid/translucent `background-color` layers only.
15
16
  // It does NOT sample `background-image`s, gradients, blurred backdrops, video, or
@@ -24,9 +25,10 @@
24
25
  // and `oklch()` (the engine's OWN emission form since 0.4.0, and what a browser
25
26
  // serialises `background-color` back to for an oklch-painted surface). Other
26
27
  // modern forms — `lab()`, `lch()`, `color(srgb …)`, `color-mix()`, `hsl()`,
27
- // named colours beyond `transparent` — are NOT parsed and return `null` (a
28
- // dropped layer). If a surface's background is authored in one of those, pass the
29
- // effective background explicitly via the `background` option.
28
+ // named colours beyond `transparent` — are NOT parsed and currently become a
29
+ // dropped layer for compatibility. That is not safe evidence: pass the
30
+ // background explicitly. Issue #283 owns the typed `Unknown` replacement for
31
+ // unsupported syntax, missing opaque bases and incomplete traversal.
30
32
 
31
33
  /** @typedef {[number, number, number, number]} Rgba r,g,b in 0..255, a in 0..1 */
32
34
 
@@ -183,9 +185,16 @@ function oklchAlpha(tok) {
183
185
  export function compositeOver(top, bottom) {
184
186
  const at = top[3];
185
187
  const ab = bottom[3];
186
- const a = at + ab * (1 - at);
188
+ // Affine-форма математически равна expanded source-over и фиксирует
189
+ // объявленный byte-scale binary64 operation order. Это numerical profile,
190
+ // не утверждение глобальной монотонности: округление может менять локальный
191
+ // порядок соседних значений, а legacy WCAG EOTF дополнительно имеет seam.
192
+ const a = ab + at * (1 - ab);
187
193
  if (a === 0) return [0, 0, 0, 0];
188
- const c = (i) => (top[i] * at + bottom[i] * ab * (1 - at)) / a;
194
+ const c = (i) => {
195
+ const bottomPremultiplied = bottom[i] * ab;
196
+ return (bottomPremultiplied + at * (top[i] - bottomPremultiplied)) / a;
197
+ };
189
198
  return [c(0), c(1), c(2), a];
190
199
  }
191
200
 
@@ -326,8 +335,8 @@ export function parseCssColorCached(css) {
326
335
  return hit;
327
336
  }
328
337
 
329
- /** WCAG 2.1 relative luminance of r,g,b channels (0..255) — the normative
330
- * 0.03928 / 12.92 / 2.4 constants, matching `adapt-theme`'s floor semantics. */
338
+ /** Relative luminance of r,g,b channels (0..255) in the frozen original WCAG
339
+ * 2.1 (2018) profile: 0.03928 / 12.92 / 2.4, matching `adapt-theme`. */
331
340
  function wcagLumChannels(r, g, b) {
332
341
  const lin = (c) => {
333
342
  const s = c / 255;
@@ -402,10 +411,10 @@ export function lerpPairHex(pair, t) {
402
411
  return toHex([linearToSrgb(lin[0]) * 255, linearToSrgb(lin[1]) * 255, linearToSrgb(lin[2]) * 255]);
403
412
  }
404
413
 
405
- /** WCAG relative luminance of `lerpPairHex(pair, t)` WITHOUT the `#RRGGBB`
406
- * round-trip: channels are quantised to the exact bytes `toHex` would emit,
407
- * then fed to the normative formula — so strict-mode bisection over `t` is
408
- * ~20 flops instead of serialise + re-parse, at identical results. */
414
+ /** Relative luminance of `lerpPairHex(pair, t)` in the frozen legacy WCAG 2.1
415
+ * (2018) profile, WITHOUT the `#RRGGBB` round-trip: channels are quantised to
416
+ * the exact bytes `toHex` would emit, then fed to the same profile formula.
417
+ * This preserves value parity; it does not prove bisection monotonicity. */
409
418
  export function lerpPairLuminance(pair, t) {
410
419
  if (t <= 0) return wcagLumChannels(pair.aBytes[0], pair.aBytes[1], pair.aBytes[2]);
411
420
  if (t >= 1) return wcagLumChannels(pair.bBytes[0], pair.bBytes[1], pair.bBytes[2]);
@@ -442,13 +451,13 @@ export function compositeStackToHex(layersFrontToBack, opaqueBase) {
442
451
  }
443
452
 
444
453
  /**
445
- * The opaque effective background `#RRGGBB` visible behind `element`'s own
446
- * content, by walking ancestors and compositing their `background-color`s.
454
+ * Legacy opaque reference-background estimate for the supported
455
+ * `background-color` subset. This is not a browser pixel observation.
447
456
  *
448
457
  * Walks from `element` upward, collecting each `background-color` layer, and
449
458
  * stops at the first fully-opaque layer (which becomes the base). If the chain
450
- * reaches the root without an opaque layer, `fallback` (default white) is the
451
- * base — matching how a browser shows the page's default canvas.
459
+ * reaches the root without an opaque layer, `fallback` (default white) is used
460
+ * as an explicit compatibility assumption; it is not evidence of the canvas.
452
461
  *
453
462
  * Pure and injectable: pass `getStyle` and `parentOf` to test without a DOM; in
454
463
  * the browser they default to `getComputedStyle` and `el.parentElement`.
package/index.d.ts CHANGED
@@ -11,13 +11,46 @@ export {
11
11
  LabColors,
12
12
  } from "./pkg/labcolors.js";
13
13
 
14
+ // Curated public schema/result surface. wasm-bindgen's InitOutput and raw
15
+ // __wbg_* ABI helpers remain implementation details.
14
16
  export type {
15
17
  ThemeName,
16
18
  SolvedColor,
17
- TranslucentRole,
18
19
  NoneRole,
19
20
  UnreachableRole,
21
+ TranslucentRole,
22
+ GlowDecisionProfileV1,
23
+ GlowLayerRecipeProfileV1,
24
+ GlowDiagnosticProfileV1,
25
+ GlowTargetStatusV1,
26
+ NumericalIndeterminacyV1,
27
+ GlowBitExactDecisionGuaranteeV1,
28
+ GlowLegacyDecisionGuaranteeV1,
29
+ GlowDecisionGuaranteeV1,
30
+ GlowDeterminateRoleBase,
31
+ GlowStableExactNoopRole,
32
+ GlowLegacyReachedRole,
33
+ GlowLegacyUnreachableRole,
34
+ GlowDeterminateRole,
35
+ GlowIndeterminateRoleBase,
36
+ GlowIndeterminateRole,
37
+ GlowRole,
38
+ MaterialAlphaGuaranteeBaseV1,
39
+ MaterialBisectionBracketGuaranteeV1,
40
+ MaterialTransparentEndpointGuaranteeV1,
41
+ MaterialOpaqueEndpointGuaranteeV1,
42
+ MaterialAlphaGuaranteeV1,
43
+ MaterialRoleBase,
44
+ MaterialSatisfiedTransparentRole,
45
+ MaterialSatisfiedBracketRole,
46
+ MaterialDegradedOpaqueRole,
47
+ MaterialRole,
20
48
  RoleResult,
49
+ ThemeAnchors,
50
+ LadderSource,
51
+ LadderPositionV1,
52
+ RoleRecipe,
53
+ ThemeConfig,
21
54
  ResolvedTheme,
22
55
  } from "./pkg/labcolors.js";
23
56
 
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "@labpics/colors",
3
- "version": "0.9.0",
4
- "description": "Framework-agnostic contrast engine: resolve accessible, perceptually-anchored colour roles for any background. WASM core, zero runtime dependencies.",
3
+ "version": "0.10.0",
4
+ "packageManager": "npm@11.9.0",
5
+ "description": "Contextual compiler and runtime resolver for client-owned color-token contracts. WASM core, zero runtime dependencies.",
5
6
  "type": "module",
6
7
  "license": "MIT",
7
8
  "publishConfig": {
@@ -35,9 +36,12 @@
35
36
  "default": "./effective-bg.js"
36
37
  },
37
38
  "./pkg/labcolors_bg.wasm": "./pkg/labcolors_bg.wasm",
39
+ "./build-metadata.json": "./build-metadata.json",
38
40
  "./package.json": "./package.json"
39
41
  },
40
42
  "files": [
43
+ "LICENSE",
44
+ "build-metadata.json",
41
45
  "index.js",
42
46
  "index.d.ts",
43
47
  "apply-theme.js",
@@ -55,13 +59,29 @@
55
59
  ],
56
60
  "scripts": {
57
61
  "//build": "wasm-pack resolves --out-dir relative to the CRATE dir (crates/labcolors-wasm), not the cwd, so the ../../packages path is correct and unambiguous regardless of where npm runs it.",
58
- "build": "wasm-pack build ../../crates/labcolors-wasm --release --target web --out-dir ../../packages/colors/pkg --out-name labcolors",
62
+ "build": "wasm-pack build ../../crates/labcolors-wasm --release --target web --out-dir ../../packages/colors/pkg --out-name labcolors --locked",
59
63
  "typecheck": "tsc --noEmit -p tsconfig.json",
60
- "test": "node --test"
64
+ "test": "node --test",
65
+ "prepack": "npm run build && node ../../scripts/prepare-npm-package.mjs",
66
+ "release:verify": "node ../../scripts/verify-package-release.mjs"
61
67
  },
62
68
  "devDependencies": {
63
69
  "typescript": "^5.5.0"
64
70
  },
65
71
  "types": "./index.d.ts",
66
- "sideEffects": false
72
+ "sideEffects": false,
73
+ "keywords": [
74
+ "color",
75
+ "oklch",
76
+ "contrast",
77
+ "apca",
78
+ "wcag",
79
+ "theme",
80
+ "design-tokens",
81
+ "wasm",
82
+ "labpics"
83
+ ],
84
+ "engines": {
85
+ "node": ">=22.11.0"
86
+ }
67
87
  }