RecipesCam/HSL_PORT.md

Port HSL (selective colour mixer) — docker/frontend → Android

Tài liệu này mô tả chính xác cách đưa tính năng HSL của bản web (docker/frontend/) sang app Android (Expo + Skia, source ở repo root).

Web là bản tham chiếu: docker/frontend/shared/ là bản copy của src/ bên Android nhưng đã đi trước. Hướng port là:

docker/frontend/shared/**  →  src/**
docker/frontend/src/**     →  src/components/**, App.tsx

---

0. Phạm vi — chỉ HSL

Diff giữa src/ và docker/frontend/shared/ không chỉ có HSL. Các delta sau nằm cùng file nhưng KHÔNG thuộc tài liệu này, tuyệt đối không port kèm:

Delta web-only	Nơi xuất hiện	Kết luận
WB white/black point (whites/blacks)	types, paramDefs, toneShader (wh/bl), defaultRecipes	BỎ
Base filter classic-vivid (sim-classic-vivid)	types, toneShader FILM_TONE, defaultRecipes	BỎ
Frame wallframe-landscape	types FrameId, recipeShare FRAMES, chips ROTATE/wall	BỎ
GLOW_T0/GLOW_T1 0.55/0.85 → 0.45/0.75	toneShader	BỎ — đây là chỉnh demo của web; Android giữ 0.55/0.85
exifWrite.ts diff (22 dòng)	—	không liên quan HSL

Chỉ port: types HSL, colorUtils HSL, toneShader mixer, recipeShare sanitize, defaultRecipes 3 field toàn ảnh, UI tab HSL.

---

1. Ngữ nghĩa (đọc trước khi code)

Mixer chọn màu theo 8 dải hue. Mỗi dải có 3 knob [hue, sat, lum], mỗi knob -10..+10:

• hue — xoay hue, ±30° khi full (acc.x * 30/360).
• sat — scale saturation, -10 = xám (s * (1 + acc.y), acc.y = -1).
• lum — cộng lightness, ±0.25 khi full (acc.z * 0.25), additive nên không đảo ramp.

Ba knob toàn ảnh (hslHue, hslSat, hslLum) là "seed" của accumulator: mọi hue nhận full weight.

Quy tắc bất biến — port phải giữ đúng:

1. Partition of unity. Weight mỗi dải là tent tuyến tính: full tại anchor của nó, về 0 tại anchor hai dải kề. Hai tent kề cắt nhau đúng tại 0.5 ở midpoint ⇒ 8 weight cộng lại bằng 1 tại mọi hue. Không pixel nào bị tính hai lần, không hue nào rơi vào khe.
2. Anchor cố định 1 nguồn. HSL_BANDS (cho chip) và BAND_BLOCK (cho shader) sinh từ cùng bảng qua hslBandGaps() ⇒ anchor không thể lệch.
3. Gate xám. gate = smoothstep(0.0, 0.08, hsl.y) — pixel có saturation < 8% bị loại khỏi weight, vì rgb2hsl trả hue 0 cho xám và nếu không gate thì mọi pixel trung tính sẽ chạy theo dải RED.
4. gl KHÔNG gate. Lightness toàn ảnh (gl) được cộng sau gate, nên ảnh đã bị -SAT rút về xám vẫn còn +LUM.
5. Monochrome tắt mixer. if (!colour) hslOn = 0; — stock đen trắng không có hue để chọn.
6. Dải toàn 0 bị xoá. Band [0,0,0] không bao giờ vào recipe; kéo knob về 0 thì dải biến mất không để lại dấu.
7. Mixer chạy CUỐI, sau split-tone/kv và sau vibrance — để band edit được đánh giá trên màu người dùng thực sự sample.

---

2. src/types/index.ts

Thêm 2 type (đặt cạnh BaseFilter/ColorAdjustments):

export type HslBandId = 'red' | 'orange' | 'yellow' | 'green' | 'aqua' | 'blue' | 'purple' | 'magenta';
// [hue, sat, lum], mỗi số -10..+10; dải toàn 0 bị xoá khỏi recipe
export type HslBand = [number, number, number];

Trong interface ColorAdjustments (sau vibrance?, trước exposureCompensation):

  hslBands?: Partial<Record<HslBandId, HslBand>>; // selective colour: mỗi dải [hue, sat, lum], -10..+10
  hslHue?: number; // -10..+10 xoay hue toàn ảnh
  hslSat?: number; // -10..+10 scale saturation toàn ảnh
  hslLum?: number; // -10..+10 cộng lightness toàn ảnh

hslBands là một field lồng, không phải 24 field phẳng — đây là lý do nó cần gate riêng khi import (mục 5).

---

3. src/utils/colorUtils.ts

File Android hiện chỉ có kelvinToRGB, getSkiaColorMatrix, applyExposureGain. Thêm nguyên khối sau lên đầu file (sau import):

import { ColorAdjustments, BaseFilter, HslBand, HslBandId } from '../types';

// 8 dải của mixer chọn màu, và anchor hue mỗi dải đứng (độ trên vòng HSL).
// Anchor cố tình không đều: red/orange/yellow cách nhau 30° vì mắt phân biệt
// kỹ vùng này, còn phía blue là một khúc 60°. TONE_SKSL dựng đúng 8 weight này
// từ bảng dưới, nên anchor chip sửa và anchor shader mask không thể lệch.
//
// `label` là chữ chip in ra — chuỗi của app, KHÔNG nằm trong i18n.
export const HSL_BANDS: { id: HslBandId; hue: number; label: string }[] = [
  { id: 'red', hue: 0, label: 'RED' },
  { id: 'orange', hue: 30, label: 'ORANGE' },
  { id: 'yellow', hue: 60, label: 'YELLOW' },
  { id: 'green', hue: 120, label: 'GREEN' },
  { id: 'aqua', hue: 180, label: 'AQUA' },
  { id: 'blue', hue: 240, label: 'BLUE' },
  { id: 'purple', hue: 280, label: 'PURPLE' },
  { id: 'magenta', hue: 320, label: 'MAGENTA' },
];

// Hue (độ) của hai dải kề mỗi dải, đúng như TONE_SKSL cần. Suy ra từ HSL_BANDS
// để hai bảng không thể cãi nhau: tent weight của một dải về 0 tại anchor của
// hai dải kề, khiến 8 weight là partition of unity trên vòng hue (cộng = 1 tại
// mọi hue).
export function hslBandGaps(): { id: HslBandId; hue: number; left: number; right: number }[] {
  const n = HSL_BANDS.length;
  return HSL_BANDS.map((b, i) => {
    const prev = HSL_BANDS[(i - 1 + n) % n].hue;
    const next = HSL_BANDS[(i + 1) % n].hue;
    // Red (0°) wrap: dải kề trái là magenta 320°, tức 40° về sau.
    return { id: b.id, hue: b.hue, left: (b.hue - prev + 360) % 360, right: (next - b.hue + 360) % 360 };
  });
}

// 0..255 sRGB → HSL. Hue theo độ, saturation/lightness 0..1 — chiều ngược của
// hsl2rgb trong shader, và là thứ readout của eyedropper in ra.
export function rgbToHsl(r: number, g: number, b: number): { h: number; s: number; l: number } {
  const R = r / 255;
  const G = g / 255;
  const B = b / 255;
  const mx = Math.max(R, G, B);
  const mn = Math.min(R, G, B);
  const l = (mx + mn) / 2;
  const d = mx - mn;
  if (d < 1e-6) return { h: 0, s: 0, l };
  const s = l > 0.5 ? d / (2 - mx - mn) : d / (mx + mn);
  let h: number;
  if (mx === R) h = ((G - B) / d + (G < B ? 6 : 0)) * 60;
  else if (mx === G) h = ((B - R) / d + 2) * 60;
  else h = ((R - G) / d + 4) * 60;
  return { h, s, l };
}

// Dải mà một hue sample thuộc về: anchor gần nhất. Các dải chồng nhau trong
// shader, nên hàm này chỉ quyết định ruler đang trỏ vào dải nào.
export function nearestHslBand(hue: number): HslBandId {
  const wrapped = ((hue % 360) + 360) % 360;
  let best = HSL_BANDS[0];
  let bestD = 361;
  for (const band of HSL_BANDS) {
    const d = Math.abs(((wrapped - band.hue + 540) % 360) - 180);
    if (d < bestD) {
      bestD = d;
      best = band;
    }
  }
  return best.id;
}

// Một band triple như khi lưu: số nguyên -10..10, dải toàn 0 bị xoá để recipe
// chỉ mang theo thứ người dùng thực sự đổi.
const clamp10 = (v: unknown): number =>
  typeof v === 'number' && Number.isFinite(v) ? Math.max(-10, Math.min(10, Math.round(v))) : 0;

export function sanitizeHslBands(raw: unknown): Partial<Record<HslBandId, HslBand>> | undefined {
  if (!raw || typeof raw !== 'object') return undefined;
  const out: Partial<Record<HslBandId, HslBand>> = {};
  for (const band of HSL_BANDS) {
    const v = (raw as Record<string, unknown>)[band.id];
    if (!Array.isArray(v) || v.length !== 3) continue;
    const triple: HslBand = [clamp10(v[0]), clamp10(v[1]), clamp10(v[2])];
    if (triple[0] || triple[1] || triple[2]) out[band.id] = triple;
  }
  return Object.keys(out).length ? out : undefined;
}

Không sửa getSkiaColorMatrix: mixer nằm ở tone shader, matrix 4×5 không làm được per-pixel hue.

---

4. src/utils/toneShader.ts — shader mixer

Đây là phần lõi. Sáu sửa đổi, theo thứ tự trong file.

4.1 Import + BAND_BLOCK

import { BaseFilter, ColorAdjustments } from '../types';
import { HSL_BANDS, hslBandGaps } from './colorUtils';

Thêm trước export const TONE_SKSL:

// Tám dòng band của mixer trong TONE_SKSL, sinh từ HSL_BANDS để anchor và gap
// trong shader chính là số mà chip dựng ra. Mỗi dòng đọc 3 giá trị của dải nó
// với index HẰNG — SkSL chỉ index uniform array bằng hằng, nên block này phải
// unroll chứ không loop được.
const BAND_BLOCK = hslBandGaps()
  .map(
    (b, i) => `    float w${i} = bandW(hd, ${b.hue.toFixed(1)}, ${b.left.toFixed(1)}, ${b.right.toFixed(1)}) * gate;
    acc += vec3(w${i} * hslH[${i}], w${i} * hslS[${i}], w${i} * hslL[${i}]);\n`
  )
  .join('');

4.2 Comment header

Thêm vào khối comment đầu file (cạnh vib):

// hslOn/hslH/hslS/hslL - mixer chọn màu: 8 dải hue, mỗi dải một hue shift, một
//       saturation scale và một lightness offset (-1..1, từ knob -10..10). Dải
//       nào sở hữu pixel nào được quyết định Ở ĐÂY, per-pixel theo hue — nên
//       khác mọi thứ phía trên, 8 dải không phải một phép move toàn cục và
//       không thể nằm trong colour matrix. Xem band block ở cuối TONE_SKSL.
// gh/gs/gl - move toàn ảnh của mixer: đúng ba đại lượng đó cho TOÀN ảnh, nên
//       chúng chỉ là giá trị khởi tạo của accumulator và mọi hue nhận full
//       weight. Lightness KHÔNG bị gate theo saturation (khác band), nên ảnh bị
//       -SAT rút về xám vẫn trả lời +LUM.

4.3 Uniform khai báo trong TONE_SKSL

Thêm sau uniform float ccb; (Android không có wh/bl, nên HSL nối thẳng sau ccb):

uniform float hslOn;
uniform float hslH[8];
uniform float hslS[8];
uniform float hslL[8];
uniform float gh;
uniform float gs;
uniform float gl;

Rồi ngay trước vec4 main(vec2 xy), thêm 4 helper + mixer vào chuỗi SkSL:

// sRGB <-> HSL. Mixer làm việc trong HSL vì đó là không gian knob được đặt tên
// theo: một hue shift không được đổi độ sáng của màu, và một lightness move
// không được đổi hue — đúng thứ mà scale RGB làm sai.
vec3 rgb2hsl(vec3 c) {
  float mx = max(max(c.r, c.g), c.b);
  float mn = min(min(c.r, c.g), c.b);
  float l = (mx + mn) * 0.5;
  float d = mx - mn;
  if (d < 0.00001) return vec3(0.0, 0.0, l);
  float s = l > 0.5 ? d / max(0.00001, 2.0 - mx - mn) : d / max(0.00001, mx + mn);
  float h;
  if (mx == c.r) h = (c.g - c.b) / d + (c.g < c.b ? 6.0 : 0.0);
  else if (mx == c.g) h = (c.b - c.r) / d + 2.0;
  else h = (c.r - c.g) / d + 4.0;
  return vec3(h / 6.0, s, l);
}
float hueChannel(float p, float q, float t) {
  t = fract(t);
  if (t < 1.0 / 6.0) return p + (q - p) * 6.0 * t;
  if (t < 0.5) return q;
  if (t < 2.0 / 3.0) return p + (q - p) * (2.0 / 3.0 - t) * 6.0;
  return p;
}
vec3 hsl2rgb(vec3 hsl) {
  if (hsl.y < 0.00001) return vec3(hsl.z);
  float q = hsl.z < 0.5 ? hsl.z * (1.0 + hsl.y) : hsl.z + hsl.y - hsl.z * hsl.y;
  float p = 2.0 * hsl.z - q;
  return vec3(
    hueChannel(p, q, hsl.x + 1.0 / 3.0),
    hueChannel(p, q, hsl.x),
    hueChannel(p, q, hsl.x - 1.0 / 3.0)
  );
}
// Mức sở hữu một hue của một dải: full tại anchor của dải, giảm tuyến tính về 0
// tại anchor hai dải kề (gap không đều — red cách orange 30° và cách magenta
// 40°). Tính tuyến tính là mấu chốt: hai tent kề cắt nhau đúng 0.5 tại midpoint,
// nên 8 weight cộng lại bằng 1 tại mọi hue. Không pixel nào bị tính hai lần,
// không pixel nào rơi vào khe, và hue nằm đúng anchor nhận full giá trị của dải
// đó thay vì một phần.
float bandW(float hue, float anchor, float gapL, float gapR) {
  float d = mod(hue - anchor + 180.0, 360.0) - 180.0;
  return d <= 0.0 ? max(0.0, 1.0 + d / gapL) : max(0.0, 1.0 - d / gapR);
}

4.4 Mixer trong main() — thay đoạn kết

Trong main, đoạn cuối Android hiện là:

  float kv = 1.0 + vib * 0.75 * (1.0 - chroma);
  return vec4(clamp(mix(vec3(l2), rgb, kv), 0.0, 1.0), c.a);
}

Đổi thành:

  float kv = 1.0 + vib * 0.75 * (1.0 - chroma);
  rgb = clamp(mix(vec3(l2), rgb, kv), 0.0, 1.0);
  // Selective colour theo dải hue — move CUỐI, để một band edit được đánh giá
  // trên đúng màu người dùng sample từ render.
  //
  // Pixel xám bị loại trước khi đọc weight: rgb2hsl trả hue 0 cho nó, nên nếu
  // không gate thì MỌI pixel trung tính trong khung sẽ bị coi là đỏ nguyên chất
  // và trôi theo dải red. Dưới 8% saturation thì cũng không có hue để move.
  //
  // Ba accumulator là giá trị band nhân mức sở hữu, nên một hue nằm giữa hai
  // anchor nhận hỗn hợp tỉ lệ của hai edit — đúng blend mà weight đã cộng ra.
  // Hue là phép xoay (±30° khi full), saturation là scale (0 = xám tại -10),
  // lightness là additive (±0.25 khi full) nên không thể đảo ramp.
  if (hslOn > 0.5) {
    vec3 hsl = rgb2hsl(rgb);
    float gate = smoothstep(0.0, 0.08, hsl.y);
    float hd = hsl.x * 360.0;
    // Move toàn ảnh là seed: mọi hue nhận hue turn và saturation scale ở full
    // weight, các dải cộng thêm phần của mình lên trên. Lightness được cộng
    // bên dưới KHÔNG gate, nên nó vẫn nâng một màu đã bị -SAT rút về xám.
    vec3 acc = vec3(gh, gs, 0.0) * gate;
${BAND_BLOCK}    hsl.x = fract(hsl.x + acc.x * (30.0 / 360.0));
    hsl.y = clamp(hsl.y * (1.0 + acc.y), 0.0, 1.0);
    hsl.z = clamp(hsl.z + (acc.z + gl) * 0.25, 0.0, 1.0);
    rgb = hsl2rgb(hsl);
  }
  return vec4(clamp(rgb, 0.0, 1.0), c.a);
}

${BAND_BLOCK} phải nằm trong template literal — 8 dòng sinh ra nối liền ngay trước hsl.x =. Giữ đúng dạng đó, đừng thụt lề lại: SkSL không quan tâm, nhưng giữ khớp bản web để diff sau này đọc được.

4.5 ToneUniforms

Thêm vào interface (sau ccb):

  hslOn: number; // 1 khi có band hoặc move toàn ảnh được set (0 = skip mixer)
  hslH: number[]; // 8 × -1..1 theo dải, thứ tự HSL_BANDS (±30° hue khi full)
  hslS: number[]; // 8 × -1..1 (saturation scale, -1 = xám)
  hslL: number[]; // 8 × -1..1 (lightness additive, ±0.25 khi full)
  gh: number; // -1..1 xoay hue toàn ảnh (±30° khi full)
  gs: number; // -1..1 scale saturation toàn ảnh
  gl: number; // -1..1 cộng lightness toàn ảnh (±0.25 khi full, ungated)

4.6 getToneUniforms

Trong thân hàm, trước return {:

  // Selective colour: một slot mỗi dải, theo thứ tự HSL_BANDS, để flat buffer
  // khớp với array của shader. Dải người dùng chưa move giữ ba số 0 và chỉ tốn
  // slot của nó.
  const bands = adj.hslBands ?? {};
  const tenth = (v: unknown) =>
    typeof v === 'number' && Number.isFinite(v) ? Math.max(-1, Math.min(1, v / 10)) : 0;
  const hslH: number[] = [];
  const hslS: number[] = [];
  const hslL: number[] = [];
  let hslOn = 0;
  for (const band of HSL_BANDS) {
    const v = bands[band.id];
    const [h, s, l] = v ? [tenth(v[0]), tenth(v[1]), tenth(v[2])] : [0, 0, 0];
    hslH.push(h);
    hslS.push(s);
    hslL.push(l);
    if (h || s || l) hslOn = 1;
  }
  // Stock monochrome không có hue để chọn theo.
  if (!colour) hslOn = 0;
  // Move toàn ảnh của mixer, mọi hue nhận full weight.
  const gh = tenth(adj.hslHue);
  const gs = tenth(adj.hslSat);
  const gl = tenth(adj.hslLum);
  if (colour && (gh || gs || gl)) hslOn = 1;

Và thêm vào object return (cuối, sau ccb):

    hslOn,
    hslH,
    hslS,
    hslL,
    gh,
    gs,
    gl,

colour đã có sẵn trong hàm (const colour = baseFilter !== 'monochrome'). Đặt khối HSL sau dòng đó.

4.7 toneUniformArray

export function toneUniformArray(u: ToneUniforms): number[] {
  return [
    u.dr, u.hl, u.sh, u.vib,
    u.shT[0], u.shT[1], u.shT[2], u.hlT[0], u.hlT[1], u.hlT[2], u.cc, u.ccb,
    u.hslOn, ...u.hslH, ...u.hslS, ...u.hslL, u.gh, u.gs, u.gl,
  ];
}

Tổng độ dài: 12 + 1 + 8 + 8 + 8 + 3 = 40.

4.8 toneIsActive

u.hslOn !== 0 || là clause đầu tiên:

export function toneIsActive(u: ToneUniforms): boolean {
  return (
    u.hslOn !== 0 ||
    u.dr !== 0 ||
    ... // phần còn lại giữ nguyên
  );
}

---

5. src/utils/recipeShare.ts

Import:

import { sanitizeHslBands } from './colorUtils';

Trong importRecipeXml, trước dòng const frameId: FrameId = ...:

  // Mixer là adjustment duy nhất đến dưới dạng object lồng, nên là cái duy nhất
  // cần gate riêng: band id lạ bị bỏ, mọi giá trị bị kẹp về range knob, và một
  // dải để nguyên 0 bị xoá thay vì mang theo vô ích.
  adjustments.hslBands = sanitizeHslBands(raw.adjustments.hslBands);

exportRecipeXml không cần sửa: adjustments được nhân bản nguyên khối vào payload JSON, hslBands tự đi theo. Format .recipe (XML bọc hex xorshift) giữ nguyên version="1".

storageUtils.getAllRecipes merge { ...DEFAULT_ADJUSTMENTS, ...r.adjustments } — đủ cho 3 field toàn ảnh. hslBands từ storage là do chính app ghi nên không cần sanitize; nếu muốn chắc, gọi thêm sanitizeHslBands trong fill.

---

6. src/utils/defaultRecipes.ts

Thêm 3 field vào DEFAULT_ADJUSTMENTS (sau vibrance nếu có, trước exposureCompensation):

  hslHue: 0,
  hslSat: 0,
  hslLum: 0,

Không thêm hslBands vào đây — nó optional và undefined mới là "không có dải nào"; thêm hslBands: {} sẽ làm differs() trong App.tsx báo dirty sai.

---

7. Uniform buffer — các điểm Android phải sửa thêm

exportEngine.ts không cần sửa: nó gọi toneUniformArray(tone) + toneIsActive(tone), cả hai đã tự mang HSL.

nativeExport.ts (dev probe, EXPO_PUBLIC_NATIVE_EXPORT) không mang HSL — giống colorChrome, nó chỉ truyền toneDr/toneHl/toneSh vào PhotoAdjust. Ghi rõ trong comment cạnh comment "port them into applyTone()" hiện có; không cần làm gì thêm cho tới khi native path thành đường chính.

7.1 src/components/Viewfinder.tsx — BẮT BUỘC, dễ sót

Camera worklet đọc flat buffer qua toneSync, có hai chỗ hardcode theo độ dài cũ:

// dòng ~499
const toneSync = useMemo(
  () => createSynchronizable<number[]>(new Array(10).fill(0)),
  [],
);

// dòng ~1270
const tone = toneSync.getDirty();
const hasTone =
  toneEffect != null &&
  (tone[0] !== 0 || tone[1] !== 0 || ... || tone[11] !== 0);

Sửa:

1. new Array(40).fill(0) — đúng bằng độ dài toneUniformArray.
2. hasTone thêm tone[12] !== 0 (đây là hslOn).

Nếu bỏ sót, worklet đọc undefined ở các slot mới ⇒ uniform NaN ⇒ cả tone pass hỏng trên preview camera, không chỉ HSL.

Library (declarative <Shader>) — thêm key vào object toneUniforms (dòng ~2999):

  const toneUniforms = {
    dr: toneParams[0],
    hl: toneParams[1],
    sh: toneParams[2],
    vib: toneParams[3],
    shTr: toneParams[4],
    shTg: toneParams[5],
    shTb: toneParams[6],
    hlTr: toneParams[7],
    hlTg: toneParams[8],
    hlTb: toneParams[9],
    cc: toneParams[10],
    ccb: toneParams[11],
    hslOn: toneParams[12],
    hslH: toneParams.slice(13, 21),
    hslS: toneParams.slice(21, 29),
    hslL: toneParams.slice(29, 37),
    gh: toneParams[37],
    gs: toneParams[38],
    gl: toneParams[39],
  };

toneOn = toneParams.some((v) => v !== 0) giữ nguyên — buffer phẳng nên vẫn đúng.

Cần xác nhận trên máy: nhánh declarative <Shader uniforms> của RN Skia phải nhận array uniform (float hslH[8]). Nếu nó flatten/không nhận, chuyển nhánh library preview sang makeShaderWithChildren(toneUniformArray(tone), [imageShader]) như camera/export đã làm — cùng một nguồn số, bỏ hẳn object named-uniform.

---

8. UI Android

8.1 src/components/ToolRail.tsx

export type TabId = 'recipes' | 'favorites' | 'iq' | 'wb' | 'filters' | 'hsl' | 'frame';

Thêm vào TOOLS, giữa filters và frame (web đặt HSL cùng nhóm màu):

  { id: 'filters', label: 'FX' },
  { id: 'hsl', label: 'HSL' },
  { id: 'frame', label: 'FRAME' },

8.2 State — nâng lên App.tsx

Web để state HSL trong App. Android cũng phải vậy, vì cả AdjustmentPanel (chip) lẫn Viewfinder (eyedropper + panel nổi) đều cần:

const [hslBand, setHslBand] = useState<HslBandId>('red');   // dải ruler đang sửa
const [picking, setPicking] = useState(false);              // eyedropper đã arm chưa
const [hslSample, setHslSample] = useState<{ r: number; g: number; b: number } | null>(null);
const [hslPickedAt, setHslPickedAt] = useState<{ fx: number; fy: number } | null>(null); // vị trí trên ảnh

Truyền xuống Viewfinder: picking, hslPickedAt, onPickColor, và một node hslPanel (JSX panel, xem 8.5). Truyền xuống AdjustmentPanel: hslBand, onHslBand, picking, onPicking, hslSample, adjustments, onUpdateAdjustments (đã có).

Hai setter (đặt cạnh nhau, cả hai gọi onUpdateAdjustments):

// Một band triple như khi lưu. Dải về [0,0,0] bị XOÁ, và khi không còn dải nào
// thì field trả về undefined (không phải {}) để `differs(adjustments,
// DEFAULT_ADJUSTMENTS)` trong resetDirty không báo dirty sai.
const setBandKnob = (which: 0 | 1 | 2, v: number) => {
  const band = adjustments.hslBands?.[hslBand] ?? ([0, 0, 0] as HslBand);
  const next: HslBand = [band[0], band[1], band[2]];
  next[which] = Math.round(v);
  const bands = { ...adjustments.hslBands };
  if (next[0] === 0 && next[1] === 0 && next[2] === 0) delete bands[hslBand];
  else bands[hslBand] = next;
  onUpdateAdjustments({ hslBands: Object.keys(bands).length ? bands : undefined });
};

// Move toàn ảnh: một cửa cho cả ba knob, nên ruler và field nó ghi luôn là cùng
// một giá trị dù mở từ đâu.
const setHslGlobal = (which: 0 | 1 | 2, v: number) => {
  const key = which === 0 ? 'hslHue' : which === 1 ? 'hslSat' : 'hslLum';
  onUpdateAdjustments({ [key]: Math.max(-10, Math.min(10, Math.round(v))) } as Partial<ColorAdjustments>);
};

pickColor (App đưa xuống Viewfinder):

// Báo cáo của eyedropper: in màu đọc được, trỏ ruler về dải của màu đó, treo
// panel lên đúng điểm nó được đọc, rồi cất dụng cụ đi — một lần pick một màu.
const pickColor = (rgb: { r: number; g: number; b: number }, at: { fx: number; fy: number }) => {
  setHslSample(rgb);
  setHslBand(nearestHslBand(rgbToHsl(rgb.r, rgb.g, rgb.b).h));
  setHslPickedAt(at);
  setPicking(false);
};

8.3 src/components/AdjustmentPanel.tsx

1. type TabId (dòng 20) thêm | 'hsl'.
2. paramDefs: Record<TabId, ParamDef[]> thêm hsl: [] hoặc xử lý riêng trong chipRow (xem dưới). Ba knob toàn ảnh không vào PARAM_DEFS — chúng đọc/ghi field của adjustments nhưng label là HUE IMAGE/SAT IMAGE/LUM IMAGE, và mở row qua cùng cơ chế openParam với PARAM_GROUP để nút back đóng row.

Cách gọn nhất, khớp cấu trúc sẵn có: mở rộng paramDefs.hsl bằng 3 ParamDef với key là 'hsl.h' | 'hsl.s' | 'hsl.l' và onChange: (v) => setHslGlobal(which, v). Khi đó openParamDef + row slider sẵn có tự hoạt động, chip hiện value, RESET/back hoạt động.

  // Ba knob toàn ảnh của mixer không nằm trong PARAM_DEFS: chúng đọc/ghi move
  // của CHÍNH ẢNH chứ không phải một field phẳng của adjustments, và khác panel
  // trên ảnh, chúng không gắn với dải mà mixer đang trỏ.
  hsl: [0, 1, 2].map((i) => {
    const own = [a.hslHue ?? 0, a.hslSat ?? 0, a.hslLum ?? 0];
    const key = i === 0 ? 'hsl.h' : i === 1 ? 'hsl.s' : 'hsl.l';
    const name = i === 0 ? 'HUE' : i === 1 ? 'SAT' : 'LUM';
    return {
      key,
      label: `${name} IMAGE`,
      value: own[i],
      default: 0,
      min: -10,
      max: 10,
      step: 1,
      display: (v: number) => (v > 0 ? `+${v}` : String(v)),
      onChange: (v: number) => onSetHslGlobal(i as 0 | 1 | 2, v),
    };
  }),

3. Thêm case 'hsl' vào switch chipRow:

      case 'hsl': {
        // PICK arm eyedropper; 8 chip dải chọn dải mà ruler sửa; ruler do ba
        // knob bên dưới mở. Ba knob đó là move toàn ảnh, không phải của dải:
        // chip dải chọn màu cho panel trên ảnh, còn HUE/SAT/LUM dưới divider
        // move mọi hue trong khung cùng lúc.
        return chipRow([
          { key: 'hsl-pick', label: 'PICK', active: picking, onPress: () => onSetPicking(!picking) },
          ...HSL_BANDS.map((b): ChipDef => {
            const band = a.hslBands?.[b.id];
            const moved = !!band && (band[0] !== 0 || band[1] !== 0 || band[2] !== 0);
            return {
              key: `hsl-band-${b.id}`,
              label: b.label,
              // Chip gọi tên một màu nên nó hiện đúng màu đó.
              color: hslToHex(b.hue, 70, 50),
              active: hslBand === b.id,
              amberValue: hslBand !== b.id && moved,
              onPress: () => onSetHslBand(b.id),
            };
          }),
          // Divider giữ ba slider toàn ảnh ra ngoài hàng màu: hàng trên chọn
          // một màu, ba cái này move tất cả.
          { key: 'hsl-image', label: 'IMAGE', disabled: true, active: false, onPress: () => {} },
          ...paramChips(paramDefs.hsl),
        ], 8);
      }

4. ChipDef cần thêm color?: string (chip màu). Trong renderChip, khi c.color có mặt, vẽ một dot màu trước label (Android dùng View với backgroundColor):

{c.color ? <View style={{ width: 10, height: 10, borderRadius: 999, backgroundColor: c.color, marginRight: 6 }} /> : null}

Chip màu vẫn giữ text label (RED/ORANGE/…) — dot là phụ, không thay chữ.

5. Readout khi activeTab === 'hsl': Android không có cột phụ như web. Đặt một dòng readout mỏng ngay trên hàng chip (chỗ openParamDef row đang render), chỉ khi tab hsl:

{activeTab === 'hsl' && (
  <View className="flex-row items-center gap-2 px-3 py-1">
    {hslSample ? (
      <>
        <View style={{ width: 22, height: 22, borderRadius: 4, borderWidth: 1, borderColor: '#3f3f46',
                       backgroundColor: `rgb(${hslSample.r}, ${hslSample.g}, ${hslSample.b})` }} />
        <Text className="font-mono text-[11px] text-zinc-400">
          R {hslSample.r} · G {hslSample.g} · B {hslSample.b}
        </Text>
        <Text className="font-mono text-[11px] text-zinc-400">
          {Math.round(rgbToHsl(hslSample.r, hslSample.g, hslSample.b).h)}° ·{' '}
          {Math.round(rgbToHsl(hslSample.r, hslSample.g, hslSample.b).s * 100)}% ·{' '}
          {Math.round(rgbToHsl(hslSample.r, hslSample.g, hslSample.b).l * 100)}%
        </Text>
        <Text className="font-mono text-[11px] text-amber-400">{bandName}</Text>
      </>
    ) : (
      <Text className="font-mono text-[10px] tracking-widest text-zinc-500">
        BẤM PICK RỒI CHỌN MỘT MÀU TRÊN ẢNH
      </Text>
    )}
  </View>
)}

bandName = HSL_BANDS.find((b) => b.id === hslBand)?.label ?? ''.

8.4 hslToHex (dùng cho chip màu)

Copy nguyên từ web (docker/frontend/src/App.tsx dòng 108) vào src/utils/colorUtils.ts hoặc ngay trong AdjustmentPanel.tsx:

// HSL -> #rrggbb. Chip gọi tên một màu nên nó phải hiện đúng màu đó; hex là
// format duy nhất RN nhận thẳng từ chuỗi.
export function hslToHex(h: number, s: number, l: number): string {
  const k = (n: number) => (n + h / 30) % 12;
  const a = (s / 100) * Math.min(l / 100, 1 - l / 100);
  const chan = (n: number) =>
    Math.max(0, Math.min(255, Math.round(255 * (l / 100 - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1))))))
      .toString(16)
      .padStart(2, '0');
  return `#${chan(0)}${chan(8)}${chan(4)}`;
}

8.5 Eyedropper + panel nổi — src/components/Viewfinder.tsx

Đây là phần chưa có tương ứng Android, phải viết mới.

Props thêm:

  picking?: boolean;
  onPickColor?: (rgb: { r: number; g: number; b: number }, at: { fx: number; fy: number }) => void;
  hslPanel?: React.ReactNode;
  hslPanelAt?: { fx: number; fy: number } | null;

Lớp pick. Web đặt một div phủ đúng box của ảnh (box = rect ảnh sau zoom/pan, không phải cả canvas). Android đã có imageFitRect và sẵn một touch layer trong library mode (onLibTouchStart với toạ độ fraction). Cách port đúng và ít code nhất:

• Khi picking, thêm một Pressable (hoặc View với onStartShouldSetResponder) phủ đúng imageFitRect, chặn touch để pan/zoom không khởi động.
• Toạ độ fraction tính từ rect của lớp đó, không phải của canvas:

const fx = (e.nativeEvent.locationX) / rectW;
const fy = (e.nativeEvent.locationY) / rectH;
if (!(fx >= 0 && fx <= 1 && fy >= 0 && fy <= 1)) return;

• Hiện một icon eyedropper đi theo ngón tay (pick-icon của web là SVG; Android dùng lucide-react-native đã có sẵn: <Pipette size={22} color="#fff" />).
• Chỉ arm trong library mode. Camera mode không có pixel để sample (và preview là luồng sống).

Lấy màu. Web sample chính ảnh preview đã render (previewUrl), không phải file gốc — để màu đọc được đúng là màu đang thấy. Android tương đương: snapshot canvas đang vẽ. Đường ngắn nhất:

// canvasRef = useCanvasRef() trên canvas library đang vẽ `graded`.
const shot = canvasRef.current?.makeImageSnapshot();       // ảnh đã render
const px = await shot.readPixels(Math.floor(fx * shot.width()), Math.floor(fy * shot.height()), {
  width: 1, height: 1, colorType: ColorType.RGBA_8888, alphaType: AlphaType.Unpremul,
});
onPickColor({ r: px[0], g: px[1], b: px[2] }, { fx, fy });

Đọc 1 pixel từ snapshot là đủ và rẻ; cache snapshot trong lúc picking để mỗi lần chạm không phải snapshot lại.

ponytail: snapshot canvas mỗi lần pick là đủ cho một lần chạm/ảnh; nếu độ trễ cảm nhận được trên máy thật, chuyển sang decode skiaImage một lần và readPixels trên đó — nhưng khi đó màu sample là màu gốc, không phải màu đã grade, và hue có thể lệch khỏi thứ người dùng nhìn thấy nếu các knob khác đã move. Chỉ hạ cấp khi có số đo.

Panel nổi. Web đặt panel tại left = fx*100%, top = fy*100% trong box ảnh, với transform: translate(-50%, 14px), hoặc translate(-50%, calc(-100% - 14px)) khi fy > 0.55 (điểm nằm thấp thì panel treo lên trên để không rơi khỏi ảnh). Android absolute-position trong chính box đó:

{hslPanel && hslPanelAt && (
  <View
    pointerEvents="box-none"
    style={{
      position: 'absolute',
      left: 0, top: 0, width: rectW, height: rectH,
    }}
  >
    <View
      style={{
        position: 'absolute',
        left: hslPanelAt.fx * rectW,
        top: hslPanelAt.fy * rectH,
        transform: [
          { translateX: -PANEL_HALF_W },   // translate(-50%)
          { translateY: hslPanelAt.fy > 0.55 ? -(PANEL_H + 14) : 14 },
        ],
      }}
    >
      {hslPanel}
    </View>
  </View>
)}

Panel dừng pointer để không rơi xuống lớp pan của ảnh.

8.6 Panel nội dung (hslPanel)

Web dựng pickPanel ở App.tsx; Android dựng trong AdjustmentPanel (nó đã có Slider + haptics) rồi App truyền node xuống Viewfinder, hoặc dựng thẳng trong App. Nội dung:

• Swatch — màu của sample sau khi áp knob của dải đang chọn:

const picked = hslSample ? rgbToHsl(hslSample.r, hslSample.g, hslSample.b) : null;
const band = adjustments.hslBands?.[hslBand] ?? ([0, 0, 0] as HslBand);
const mixedHex = picked
  ? hslToHex(
      picked.h + band[0],
      Math.max(0, Math.min(100, picked.s * 100 + band[1])),
      Math.max(0, Math.min(100, picked.l * 100 + band[2])),
    )
  : null;

• Tên dải + hex, nút đóng ✕ (onPress={() => setHslPickedAt(null)}).
• Ba MiniSlider HUE / SAT / LUM, mỗi cái value = band[i], onValueChange = (v) => setBandKnob(i, v), và reset về 0 (web: double-click; Android: thêm một TouchableOpacity nhỏ hoặc onSlidingComplete khi |v| < 0.5 ⇒ 0). Dùng Slider (@react-native-community/slider) với minimumValue={-10} maximumValue={10} step={1}.

8.7 resetDirty — App.tsx

differs() là shallow. Với setBandKnob trả hslBands: undefined khi rỗng (8.2), differs(adjustments, DEFAULT_ADJUSTMENTS) đã bắt đúng cả hslBands lẫn hslHue/hslSat/hslLum. Không cần thêm clause — miễn là đừng để hslBands: {}.

Nếu vì lý do nào đó muốn giữ {}, thì phải thêm || Object.keys(adjustments.hslBands ?? {}).length > 0 (đúng như web) — nhưng cách undefined sạch hơn.

8.8 Camera mode + PRO gate — quyết định

• Camera mode: mixer tự động chạy trong preview camera (7.1 sửa xong toneSync), nên tab HSL cứ hiện ở cả hai mode. PICK + panel chỉ có nghĩa ở library — ở camera mode cho chip PICK ở trạng thái disabled (chip xám, không mở). Đây là điểm khác web (web library-only) và là chỗ dễ tranh cãi nhất — xác nhận với người dùng nếu muốn khác.
• PRO gate: web không gate HSL (proLookInUse() chỉ phủ PRO_FRAMES + GPS + HDF; tab HSL mở cho guest). Port giữ nguyên: HSL là tính năng LITE, không thêm vào entitlement.ts.
• RecipeCreateModal: không cần thêm dòng HSL. Web cũng không có HSL trong form CREATE — mixer chỉ chỉnh trên ảnh, recipe lưu qua adjustments khi SAVE.

---

9. Kiểm tra

9.1 Trên Android (self-check + unit)

1. HSL_BANDS / hslBandGaps — bất biến partition of unity:

// Với mọi hue 0..359, tổng 8 tent weight phải = 1 (±1e-6).
const gaps = hslBandGaps();
for (let h = 0; h < 360; h += 1) {
  const sum = gaps.reduce((s, b) => {
    const d = ((h - b.hue + 540) % 360) - 180;
    const w = d <= 0 ? Math.max(0, 1 + d / b.left) : Math.max(0, 1 - d / b.right);
    return s + w;
  }, 0);
  if (Math.abs(sum - 1) > 1e-6) throw new Error(`weights != 1 at ${h}: ${sum}`);
}

Và hslBandGaps() trả red.left = 40, red.right = 30 (wrap đúng).

2. sanitizeHslBands:

   • { red: [99, -99, 0] } → { red: [10, -10, 0] }
   • { red: [0,0,0] } → undefined
   • { red: [1,2] }, { nope: [1,2,3] } → bỏ
   • null / 'x' → undefined

3. rgbToHsl ↔ nearestHslBand: đỏ thuần (255,0,0) → red; (255,128,0) → orange; xám (128,128,128) → s = 0, nearestHslBand(0) = 'red' (rồi shader gate nó đi).

4. Shader compile — Skia.RuntimeEffect.Make(TONE_SKSL) không throw. Bắt buộc, vì ${BAND_BLOCK} nội suy vào chuỗi.

5. toneUniformArray — length === 40; hslOn ở index 12; gh/gs/gl ở 37/38/39.

6. toneIsActive — { ...all zero, hslOn: 1 } → true; { ...all zero } → false.

7. getToneUniforms — baseFilter: 'monochrome' + hslBands có giá trị ⇒ hslOn === 0; colour + hslLum: 10 ⇒ gl === 1, hslOn === 1.

8. Round-trip .recipe — recipe có hslBands: { blue: [3,-2,5], red: [0,0,0] } export rồi import: red biến mất, blue giữ nguyên; hslHue/Sat/Lum sống qua vòng.

9. Máy / emulator (kiểm tra số, không nhìn ảnh):

   • Preview camera với +10 dải RED và ảnh có mảng đỏ: sample pixel đỏ trước/sau bằng readPixels trên cùng toạ độ ⇒ hue trôi ~+30°.
   • -10 SAT dải RED trên vùng đỏ ⇒ saturation về ~0; +10 LUM ⇒ lightness tăng ~0.25.
   • hslLum = +10 trên một ảnh đã saturation = -10: lightness vẫn phải tăng (kiểm tra gl không bị gate).
   • Monochrome stock: uniform HSL toàn 0 bất kể hslBands có gì.
   • Export ra file: pixel cuối phải khớp pixel preview (cùng một toneUniformArray).

9.2 Tham chiếu hành vi từ web

Các script e2e của web là hợp đồng hành vi để đối chiếu, nằm trong scratchpad:

/home/locpham/.penguin/data/default_project/agents/default_agent/scratchpad/session-2026-09-06-18-30-42-c24c8c7b/
  hsl-test.cjs          # chips dải, setBandKnob, xoá dải toàn 0
  hsl-panel-test.cjs    # PICK -> pickColor -> panel nổi -> knob panel
  hsl-shader-test.cjs   # partition of unity + kết quả shader theo hue
  hsl-bundle.cjs        # build standalone
  hsl-entry.ts          # entry

Web đã deploy (docker/frontend) là bản chạy được để so từng bước: mở tab hsl, PICK một màu, kéo HUE/SAT/LUM trên panel và trên ruler IMAGE, đối chiếu R n · G n · B n / h° · s% · l%.

---

10. Thứ tự thực hiện (đề xuất)

1. types → 2. colorUtils (HSL_BANDS … sanitize) → 3. toneShader (4.1–4.8) → 4. self-check 9.1.1–9.1.7 chạy pass → 5. defaultRecipes + recipeShare → 6. Viewfinder buffer (7.1) — làm trước UI, nếu không preview camera sẽ vỡ → 7. ToolRail + AdjustmentPanel chip/readout → 8. Viewfinder eyedropper + panel + state App → 9. máy thật.