@1agh/maude 0.41.0 → 0.43.0

package/apps/studio/photo/filters.ts

@@ -0,0 +1,285 @@
+/**
+ * @file       photo/filters.ts — pure photo-pipeline PLANNER (Stage B, Task 4)
+ * @scope      apps/studio/photo/filters.ts
+ * @purpose    Turn a `PhotoEdit` into an ordered, plain-data description of the
+ *             compositing stack — `planPhotoPipeline(edit) → PhotoPipelineStep[]`.
+ *             This is the deterministic, testable core: it decides WHAT filters/
+ *             overlays/masks apply and in WHAT order, without ever touching a GPU.
+ *
+ * @invariant  DEPENDENCY-FREE — like `schema.ts`, this file MUST NOT import
+ *             `pixi.js`. The pixi realization (constructing real
+ *             `PIXI.ColorMatrixFilter` / `NoiseFilter` / the duotone shader /
+ *             `TilingSprite` / `Graphics` mask objects) lives in `pipeline.ts`,
+ *             which is browser-only.
+ *
+ *             WHY the split (deviation from the plan's single
+ *             `buildFilterGraph(): PIXI.Filter[]`): pixi v8 eagerly compiles a
+ *             `GlProgram` in every filter's constructor, which calls
+ *             `document.createElement('canvas')` — so constructing a filter in a
+ *             headless `bun test` throws `ReferenceError: document is not
+ *             defined`. Returning plain-data STEP specs keeps the plan's stated
+ *             Task-4 validation ("assert filter count/order, not pixel output")
+ *             genuinely runnable, and mirrors how `draw/serialize.ts` produces a
+ *             browser-free description of a render. `pipeline.ts` re-exports a
+ *             `buildFilterGraph(edit)` that realizes these steps into pixi objects.
+ *
+ * @order      Fixed, load-bearing pipeline order (filters are NOT commutative) —
+ *             `PHOTO_PIPELINE_ORDER` from schema.ts:
+ *               adjustments → duotone → grain → pattern → mask
+ *             The adjustment SUB-order (within the single color-matrix step) is
+ *             also fixed: brightness → exposure → contrast → saturation → hue →
+ *             sepia → grayscale → invert (color-matrix ops compose, so order
+ *             changes the result). Both orders are asserted by the unit tests.
+ */
+
+import type {
+  MaskPreset,
+  PatternBlend,
+  PatternType,
+  PhotoAdjustments,
+  PhotoEdit,
+} from './schema.ts';
+import { PHOTO_PIPELINE_ORDER } from './schema.ts';
+
+// ── Step vocabulary (plain data — the realizer in pipeline.ts consumes these) ──
+
+/** One color-matrix operation, with a NORMALIZED value (see schema.ts ranges).
+ *  The realizer maps each op onto the corresponding pixi ColorMatrixFilter call. */
+export type AdjustOpKind =
+  | 'brightness'
+  | 'exposure'
+  | 'contrast'
+  | 'saturation'
+  | 'hue'
+  | 'sepia'
+  | 'grayscale'
+  | 'invert';
+
+export interface AdjustOp {
+  op: AdjustOpKind;
+  /** Normalized value straight from PhotoEdit.adjustments (−1…1, deg, or 0…1). */
+  value: number;
+}
+
+/** Adjustments compile to ONE color-matrix filter carrying an ordered op list. */
+export interface AdjustmentsStep {
+  stage: 'adjustments';
+  kind: 'colorMatrix';
+  ops: AdjustOp[];
+}
+
+export interface DuotoneStep {
+  stage: 'duotone';
+  kind: 'duotone';
+  /** `#rrggbb` shadow color. */
+  colorA: string;
+  /** `#rrggbb` highlight color. */
+  colorB: string;
+  /** 0…1 crossfade between original and full duotone. */
+  intensity: number;
+}
+
+export interface GrainStep {
+  stage: 'grain';
+  kind: 'noise';
+  amount: number;
+  size: number;
+}
+
+export interface PatternStep {
+  stage: 'pattern';
+  kind: 'pattern';
+  type: PatternType;
+  scale: number;
+  opacity: number;
+  blend: PatternBlend;
+  /** `#rrggbb` ink color for the pattern tile. */
+  color: string;
+}
+
+export interface MaskStep {
+  stage: 'mask';
+  kind: 'mask';
+  /** 'none' never reaches here — an unmasked edit omits the step entirely. */
+  preset: Exclude<MaskPreset, 'none'>;
+  strength: number;
+}
+
+export type PhotoPipelineStep = AdjustmentsStep | DuotoneStep | GrainStep | PatternStep | MaskStep;
+
+// ── Sensible visual defaults (used when a section is enabled but a field unset) ─
+
+const DUOTONE_DEFAULT_A = '#111111';
+const DUOTONE_DEFAULT_B = '#ffffff';
+const DUOTONE_DEFAULT_INTENSITY = 1;
+const GRAIN_DEFAULT_AMOUNT = 0.4;
+const GRAIN_DEFAULT_SIZE = 1;
+const PATTERN_DEFAULT_TYPE: PatternType = 'dots';
+const PATTERN_DEFAULT_SCALE = 1;
+const PATTERN_DEFAULT_OPACITY = 0.5;
+const PATTERN_DEFAULT_BLEND: PatternBlend = 'normal';
+const PATTERN_DEFAULT_COLOR = '#ffffff';
+const MASK_DEFAULT_STRENGTH = 0.6;
+
+const EPS = 1e-6;
+const isSet = (v: number | undefined, origin = 0): boolean =>
+  v != null && Math.abs(v - origin) > EPS;
+
+// Fixed adjustment sub-order. See @order above.
+const ADJUST_FIELD_ORDER: readonly AdjustOpKind[] = [
+  'brightness',
+  'exposure',
+  'contrast',
+  'saturation',
+  'hue',
+  'sepia',
+  'grayscale',
+  'invert',
+];
+
+function planAdjustments(a: PhotoAdjustments | undefined): AdjustmentsStep | null {
+  if (!a) return null;
+  const ops: AdjustOp[] = [];
+  for (const field of ADJUST_FIELD_ORDER) {
+    const v = a[field];
+    if (isSet(v)) ops.push({ op: field, value: v as number });
+  }
+  return ops.length ? { stage: 'adjustments', kind: 'colorMatrix', ops } : null;
+}
+
+/**
+ * The single source of truth for "what does this edit do." Returns the ordered
+ * list of pipeline steps — a neutral/empty edit returns `[]` (the compositor
+ * then skips pixi entirely, preserving the lazy-bundle guarantee). Steps always
+ * appear in `PHOTO_PIPELINE_ORDER`.
+ */
+export function planPhotoPipeline(edit: PhotoEdit | null | undefined): PhotoPipelineStep[] {
+  if (!edit) return [];
+  const byStage: Record<string, PhotoPipelineStep | null> = {
+    adjustments: planAdjustments(edit.adjustments),
+    duotone: null,
+    grain: null,
+    pattern: null,
+    mask: null,
+  };
+
+  const d = edit.duotone;
+  if (d?.enabled && (d.intensity ?? DUOTONE_DEFAULT_INTENSITY) > EPS) {
+    byStage.duotone = {
+      stage: 'duotone',
+      kind: 'duotone',
+      colorA: d.colorA ?? DUOTONE_DEFAULT_A,
+      colorB: d.colorB ?? DUOTONE_DEFAULT_B,
+      intensity: d.intensity ?? DUOTONE_DEFAULT_INTENSITY,
+    };
+  }
+
+  const g = edit.grain;
+  if (g?.enabled && (g.amount ?? GRAIN_DEFAULT_AMOUNT) > EPS) {
+    byStage.grain = {
+      stage: 'grain',
+      kind: 'noise',
+      amount: g.amount ?? GRAIN_DEFAULT_AMOUNT,
+      size: g.size ?? GRAIN_DEFAULT_SIZE,
+    };
+  }
+
+  const p = edit.pattern;
+  if (p?.enabled && (p.opacity ?? PATTERN_DEFAULT_OPACITY) > EPS) {
+    byStage.pattern = {
+      stage: 'pattern',
+      kind: 'pattern',
+      type: p.type ?? PATTERN_DEFAULT_TYPE,
+      scale: p.scale ?? PATTERN_DEFAULT_SCALE,
+      opacity: p.opacity ?? PATTERN_DEFAULT_OPACITY,
+      blend: p.blend ?? PATTERN_DEFAULT_BLEND,
+      color: p.color ?? PATTERN_DEFAULT_COLOR,
+    };
+  }
+
+  const m = edit.mask;
+  if (m?.preset && m.preset !== 'none' && (m.strength ?? MASK_DEFAULT_STRENGTH) > EPS) {
+    byStage.mask = {
+      stage: 'mask',
+      kind: 'mask',
+      preset: m.preset,
+      strength: m.strength ?? MASK_DEFAULT_STRENGTH,
+    };
+  }
+
+  // Emit in the canonical, fixed order.
+  const out: PhotoPipelineStep[] = [];
+  for (const stage of PHOTO_PIPELINE_ORDER) {
+    const step = byStage[stage];
+    if (step) out.push(step);
+  }
+  return out;
+}
+
+// ── Pure color helper (shared by the realizer + tests) ───────────────────────
+
+/**
+ * `#rrggbb` → normalized `[r, g, b]` in 0…1. Throws on malformed input (the
+ * validator in schema.ts already rejects bad colors before persistence, so this
+ * is a belt-and-braces guard for the realizer). Kept here (pure, no pixi) so the
+ * duotone realization and its tests share one parser.
+ */
+export function hexToRgb01(hex: string): [number, number, number] {
+  const m = /^#([0-9a-fA-F]{6})$/.exec(hex);
+  if (!m) throw new Error(`hexToRgb01: not a #rrggbb color: ${hex}`);
+  const int = Number.parseInt(m[1], 16);
+  return [((int >> 16) & 0xff) / 255, ((int >> 8) & 0xff) / 255, (int & 0xff) / 255];
+}
+
+// ── GLSL for the custom duotone filter (a string — no pixi dependency) ────────
+// Duotone is a per-pixel luminance → two-color gradient-map lerp, which a linear
+// `ColorMatrixFilter` affine transform cannot express, so it needs its own
+// fragment shader. `pipeline.ts` compiles these into a `PIXI.Filter` via
+// `GlProgram.from({ vertex, fragment })`. WebGL (GLSL ES 1.00-ish, pixi v8
+// high-precision) only — the Application is pinned to `preference: 'webgl'` so
+// the WebGPU program is unnecessary (and WKWebView WebGPU is partial — Task 25).
+
+export const DUOTONE_VERT_SOURCE = /* glsl */ `
+  in vec2 aPosition;
+  out vec2 vTextureCoord;
+
+  uniform vec4 uInputSize;
+  uniform vec4 uOutputFrame;
+  uniform vec4 uOutputTexture;
+
+  vec4 filterVertexPosition(void) {
+    vec2 position = aPosition * uOutputFrame.zw + uOutputFrame.xy;
+    position.x = position.x * (2.0 / uOutputTexture.x) - 1.0;
+    position.y = position.y * (2.0 * uOutputTexture.z / uOutputTexture.y) - uOutputTexture.z;
+    return vec4(position, 0.0, 1.0);
+  }
+
+  vec2 filterTextureCoord(void) {
+    return aPosition * (uOutputFrame.zw * uInputSize.zw);
+  }
+
+  void main(void) {
+    gl_Position = filterVertexPosition();
+    vTextureCoord = filterTextureCoord();
+  }
+`;
+
+export const DUOTONE_FRAG_SOURCE = /* glsl */ `
+  in vec2 vTextureCoord;
+  out vec4 finalColor;
+
+  uniform sampler2D uTexture;
+  uniform vec3 uColorA;     // shadow color (0..1)
+  uniform vec3 uColorB;     // highlight color (0..1)
+  uniform float uIntensity; // 0..1 crossfade with the original
+
+  void main(void) {
+    vec4 src = texture(uTexture, vTextureCoord);
+    // Rec. 601 luma over UN-premultiplied color.
+    vec3 rgb = src.a > 0.0 ? src.rgb / src.a : src.rgb;
+    float luma = dot(rgb, vec3(0.299, 0.587, 0.114));
+    vec3 duo = mix(uColorA, uColorB, luma);
+    vec3 outRgb = mix(rgb, duo, uIntensity);
+    finalColor = vec4(outRgb * src.a, src.a); // re-premultiply
+  }
+`;