@pixerate/editor 0.274.0 → 0.275.0

package/dist/paint-editor/mutation-tools.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Agent tools for mutation paint (`createMutationTools`, included in `createPaintEditorToolProvider`):
+ * `list_mutations`, `read_mutation`, `answer_mutation`, and `decline_mutation`.
+ */
+import type { PresenceActorInfo } from '../animation/presence.cjs';
+import type { PaintEditorController } from './controller.cjs';
+import type { PaintAgentTool } from './hosted.cjs';
+import type { PaintDirector } from './presence.cjs';
+export interface MutationToolsOptions {
+    director?: PaintDirector;
+    actor?: PresenceActorInfo;
+}
+export declare function createMutationTools(c: PaintEditorController, options?: MutationToolsOptions): PaintAgentTool[];

package/dist/paint-editor/mutation-tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Agent tools for mutation paint (`createMutationTools`, included in `createPaintEditorToolProvider`):
+ * `list_mutations`, `read_mutation`, `answer_mutation`, and `decline_mutation`.
+ */
+import type { PresenceActorInfo } from '../animation/presence.js';
+import type { PaintEditorController } from './controller.js';
+import type { PaintAgentTool } from './hosted.js';
+import type { PaintDirector } from './presence.js';
+export interface MutationToolsOptions {
+    director?: PaintDirector;
+    actor?: PresenceActorInfo;
+}
+export declare function createMutationTools(c: PaintEditorController, options?: MutationToolsOptions): PaintAgentTool[];

package/dist/paint-editor/mutation.d.cts

@@ -0,0 +1,67 @@
+import type { RasterRect } from '../raster/surface.cjs';
+import type { PaintBrush } from './brush-model.cjs';
+import type { PaintStrokeInit } from './controller.cjs';
+import type { PenPoint } from './engine.cjs';
+export type PaintMutationState = 'settling' | 'pending' | 'claimed' | 'answered' | 'declined';
+export type PaintMutationMedium = 'wet' | 'dry';
+export interface PaintMutationStroke {
+    id: string;
+    color: string;
+    brushId: string;
+    brushName: string;
+    size: number;
+    points: PenPoint[];
+    bounds: RasterRect | null;
+}
+export interface PaintMutationInfo {
+    id: string;
+    state: PaintMutationState;
+    layerId: string;
+    medium: PaintMutationMedium;
+    bounds: RasterRect | null;
+    strokeCount: number;
+    age: number;
+    settle: number;
+    patience: number;
+    fade: number;
+    claimedBy?: string;
+    answerStrokeIds?: string[];
+    declineReason?: string;
+}
+export interface PaintMutationPng {
+    width: number;
+    height: number;
+    data: string;
+}
+export interface PaintMutationCropPng extends PaintMutationPng {
+    rect: RasterRect;
+}
+export interface PaintMutationReadResult {
+    id: string;
+    state: 'claimed';
+    layerId: string;
+    medium: PaintMutationMedium;
+    bounds: RasterRect | null;
+    fade: number;
+    strokes: PaintMutationStroke[];
+    cropPng: PaintMutationCropPng;
+    canvasPng: PaintMutationPng;
+}
+export interface PaintMutationAnswerInput {
+    strokes: ReadonlyArray<PaintStrokeInit & {
+        points: readonly PenPoint[];
+    }>;
+    layerId?: string;
+    note?: string;
+}
+export interface PaintMutationAnswerResult {
+    id: string;
+    state: 'answered';
+    layerId: string;
+    strokeIds: string[];
+    bounds: RasterRect | null;
+    dabs: number;
+    wet?: boolean;
+}
+export type PaintMutationRequestListener = (mutation: PaintMutationInfo) => void;
+export declare function mutationBrushRefusal(brush: PaintBrush): string | null;

package/dist/paint-editor/mutation.d.ts

@@ -0,0 +1,67 @@
+import type { RasterRect } from '../raster/surface.js';
+import type { PaintBrush } from './brush-model.js';
+import type { PaintStrokeInit } from './controller.js';
+import type { PenPoint } from './engine.js';
+export type PaintMutationState = 'settling' | 'pending' | 'claimed' | 'answered' | 'declined';
+export type PaintMutationMedium = 'wet' | 'dry';
+export interface PaintMutationStroke {
+    id: string;
+    color: string;
+    brushId: string;
+    brushName: string;
+    size: number;
+    points: PenPoint[];
+    bounds: RasterRect | null;
+}
+export interface PaintMutationInfo {
+    id: string;
+    state: PaintMutationState;
+    layerId: string;
+    medium: PaintMutationMedium;
+    bounds: RasterRect | null;
+    strokeCount: number;
+    age: number;
+    settle: number;
+    patience: number;
+    fade: number;
+    claimedBy?: string;
+    answerStrokeIds?: string[];
+    declineReason?: string;
+}
+export interface PaintMutationPng {
+    width: number;
+    height: number;
+    data: string;
+}
+export interface PaintMutationCropPng extends PaintMutationPng {
+    rect: RasterRect;
+}
+export interface PaintMutationReadResult {
+    id: string;
+    state: 'claimed';
+    layerId: string;
+    medium: PaintMutationMedium;
+    bounds: RasterRect | null;
+    fade: number;
+    strokes: PaintMutationStroke[];
+    cropPng: PaintMutationCropPng;
+    canvasPng: PaintMutationPng;
+}
+export interface PaintMutationAnswerInput {
+    strokes: ReadonlyArray<PaintStrokeInit & {
+        points: readonly PenPoint[];
+    }>;
+    layerId?: string;
+    note?: string;
+}
+export interface PaintMutationAnswerResult {
+    id: string;
+    state: 'answered';
+    layerId: string;
+    strokeIds: string[];
+    bounds: RasterRect | null;
+    dabs: number;
+    wet?: boolean;
+}
+export type PaintMutationRequestListener = (mutation: PaintMutationInfo) => void;
+export declare function mutationBrushRefusal(brush: PaintBrush): string | null;

package/dist/paint-editor/presence.d.cts

@@ -95,9 +95,15 @@ export declare class PaintDirector {
     private readonly options;
     private readonly clock;
     private readonly queue;
+    private readonly cancelled;
+    private currentRun;
     constructor(controller: PaintEditorController, presence: PaintPresence, options?: PaintDirectorOptions);
+    /** Cancels any queued or running performance with `key` (e.g. a mutation that was undone). */
+    cancel(key: string): void;
     /** Acts out `commands` in order for `actor`. Resolves with one result per command. */
-    perform(actor: PresenceActorInfo, commands: readonly PaintAgentCommand[]): Promise<PaintPerformanceResult[]>;
+    perform(actor: PresenceActorInfo, commands: readonly PaintAgentCommand[], options?: {
+        key?: string;
+    }): Promise<PaintPerformanceResult[]>;
     private ms;
     private where;
     /** Glides to `to`; an actor that just appeared starts there instead of the corner. */

package/dist/paint-editor/presence.d.ts

@@ -95,9 +95,15 @@ export declare class PaintDirector {
     private readonly options;
     private readonly clock;
     private readonly queue;
+    private readonly cancelled;
+    private currentRun;
     constructor(controller: PaintEditorController, presence: PaintPresence, options?: PaintDirectorOptions);
+    /** Cancels any queued or running performance with `key` (e.g. a mutation that was undone). */
+    cancel(key: string): void;
     /** Acts out `commands` in order for `actor`. Resolves with one result per command. */
-    perform(actor: PresenceActorInfo, commands: readonly PaintAgentCommand[]): Promise<PaintPerformanceResult[]>;
+    perform(actor: PresenceActorInfo, commands: readonly PaintAgentCommand[], options?: {
+        key?: string;
+    }): Promise<PaintPerformanceResult[]>;
     private ms;
     private where;
     /** Glides to `to`; an actor that just appeared starts there instead of the corner. */

package/dist/paint-editor/procedural.d.cts

@@ -29,6 +29,7 @@ import { type EffectPaintPixels } from './effect-paint.cjs';
 import { PenDabWalker, PenSmoother, type PenDab, type PenPoint, type StrokeCopy } from './engine.cjs';
 import { type PaperGrain } from './paper.cjs';
 import type { StickerArtLookup } from './sticker-art.cjs';
+import type { FilmBuffer } from './thick.cjs';
 export { DEFAULT_BRISTLE, DEFAULT_PARTICLE, DOT_ROTATIONS, DOT_TEXTURE_ORDERS, MAX_DOT_TEXTURES, normalizeBristle, normalizeParticle, PARTICLE_KINDS, PARTICLE_RENDERS, RIBBON_PAIRS, type BristleSettings, type DotRotation, type DotTextureOrder, type ParticleKind, type ParticleRender, type ParticleSettings, type RibbonPairs, } from './mark-settings.cjs';
 export interface ProceduralStrokeOptions {
     grain: PaperGrain | null;
@@ -41,6 +42,8 @@ export interface ProceduralStrokeOptions {
     effect?: EffectPaintPixels | null;
     /** Loaded sticker art, for textured dots of stickers from the sticker library. */
     stampArt?: StickerArtLookup;
+    /** Thin-film iridescence channel for procedural brushes with `iridescence`. */
+    film?: FilmBuffer | null;
 }
 /** What a coverage-building stroke engine provides to the stroke session. */
 export interface CoverageStroke {

package/dist/paint-editor/procedural.d.ts

@@ -29,6 +29,7 @@ import { type EffectPaintPixels } from './effect-paint.js';
 import { PenDabWalker, PenSmoother, type PenDab, type PenPoint, type StrokeCopy } from './engine.js';
 import { type PaperGrain } from './paper.js';
 import type { StickerArtLookup } from './sticker-art.js';
+import type { FilmBuffer } from './thick.js';
 export { DEFAULT_BRISTLE, DEFAULT_PARTICLE, DOT_ROTATIONS, DOT_TEXTURE_ORDERS, MAX_DOT_TEXTURES, normalizeBristle, normalizeParticle, PARTICLE_KINDS, PARTICLE_RENDERS, RIBBON_PAIRS, type BristleSettings, type DotRotation, type DotTextureOrder, type ParticleKind, type ParticleRender, type ParticleSettings, type RibbonPairs, } from './mark-settings.js';
 export interface ProceduralStrokeOptions {
     grain: PaperGrain | null;
@@ -41,6 +42,8 @@ export interface ProceduralStrokeOptions {
     effect?: EffectPaintPixels | null;
     /** Loaded sticker art, for textured dots of stickers from the sticker library. */
     stampArt?: StickerArtLookup;
+    /** Thin-film iridescence channel for procedural brushes with `iridescence`. */
+    film?: FilmBuffer | null;
 }
 /** What a coverage-building stroke engine provides to the stroke session. */
 export interface CoverageStroke {

package/dist/paint-editor/stroke.d.cts

@@ -15,10 +15,10 @@ import { type PaintBrush } from './brushes.cjs';
 import type { PaintGradientSource } from '../paint/gradient-paint.cjs';
 import type { EffectPaintPixels, PaintEffectPaint } from './effect-paint.cjs';
 import { type PenPoint, type StrokeCopy } from './engine.cjs';
-import type { PaperGrain } from './paper.cjs';
 import type { Affine } from './strokes.cjs';
 import type { WetStrokeDriver } from './wet.cjs';
 import { type ThickChannels } from './thick.cjs';
+import { type PaperGrain } from './paper.cjs';
 import { type Sticker } from './stickers.cjs';
 import type { StickerArtLookup } from './sticker-art.cjs';
 import type { StickerRef, StickerVariant } from '../stickers/types.cjs';
@@ -100,6 +100,20 @@ export interface StrokeSessionInit {
     light?: {
         surface: TiledSurface;
     } | null;
+    /**
+     * UV-fluorescent ink: the layer's fluorescence channel before the stroke. With it, a twin of the
+     * stroke paints the 4-channel fluorescence surface; `fluorChannel()` returns the result.
+     */
+    fluor?: {
+        surface: TiledSurface;
+    } | null;
+    /**
+     * Thermochromic ink: the layer's thermochromic channel before the stroke. With it, a twin of the
+     * stroke paints the 4-channel thermochromic surface; `thermoChannel()` returns the result.
+     */
+    thermo?: {
+        surface: TiledSurface;
+    } | null;
 }
 export interface PaintStrokeResult {
     layerId: string;
@@ -129,10 +143,18 @@ export declare class PaintStrokeSession {
     private wet;
     private readonly wetDriver;
     private thickDriver;
+    private filmBuffer;
     private stickerSpray;
     /** Light paint: the stroke's twin over the light channel, and what it left there. */
     private readonly lightTwin;
     private lightResult;
+    /** UV-fluorescent ink: the stroke's twin over the fluorescence channel, and what it left there. */
+    private readonly fluorTwin;
+    private fluorResult;
+    /** Thermochromic ink: the stroke's twin over the thermochromic channel, and what it left there. */
+    private readonly thermoTwin;
+    private thermoResult;
+    private readonly invisibleDaylight;
     /** A wet stroke that ended while the simulation was mid-batch: it commits when the driver catches up. */
     private wetEndPending;
     private readonly apply;
@@ -154,15 +176,23 @@ export declare class PaintStrokeSession {
     repaintEffect(pixels: EffectPaintPixels): void;
     /** The stroke's twin over the light channel: the same marks in grey at the brush's light amount (see `light.ts`). */
     private makeLightTwin;
+    /** The stroke's twin over the 4-channel fluorescence surface (see `heat.ts`). */
+    private makeFluorTwin;
+    /** The stroke's twin over the 4-channel thermochromic surface (see `heat.ts`). */
+    private makeThermoTwin;
     /** Light paint: the layer's light channel after the stroke, or `null` when the stroke has no twin or left it unchanged. */
     lightChannel(): TiledSurface | null;
+    /** UV-fluorescent ink: the layer's fluorescence channel after the stroke, or `null` when unchanged. */
+    fluorChannel(): TiledSurface | null;
+    /** Thermochromic ink: the layer's thermochromic channel after the stroke, or `null` when unchanged. */
+    thermoChannel(): TiledSurface | null;
     private tileTarget;
     get open(): boolean;
     /** Adds raw pen samples (document pixels). */
     push(points: readonly PenPoint[]): void;
     /** Sticker strokes: the stickers sprayed so far. */
     stickers(): Sticker[] | null;
-    /** Impasto strokes: the layer's thick-paint channels with the stroke so far. */
+    /** Impasto or iridescent strokes: the layer's thick-paint channels with the stroke so far. */
     thickChannels(): ThickChannels | null;
     /** Shows a wet stroke's progress (the wet layer's display). */
     wetUpdate(rects: RasterRect[]): void;

package/dist/paint-editor/stroke.d.ts

@@ -15,10 +15,10 @@ import { type PaintBrush } from './brushes.js';
 import type { PaintGradientSource } from '../paint/gradient-paint.js';
 import type { EffectPaintPixels, PaintEffectPaint } from './effect-paint.js';
 import { type PenPoint, type StrokeCopy } from './engine.js';
-import type { PaperGrain } from './paper.js';
 import type { Affine } from './strokes.js';
 import type { WetStrokeDriver } from './wet.js';
 import { type ThickChannels } from './thick.js';
+import { type PaperGrain } from './paper.js';
 import { type Sticker } from './stickers.js';
 import type { StickerArtLookup } from './sticker-art.js';
 import type { StickerRef, StickerVariant } from '../stickers/types.js';
@@ -100,6 +100,20 @@ export interface StrokeSessionInit {
     light?: {
         surface: TiledSurface;
     } | null;
+    /**
+     * UV-fluorescent ink: the layer's fluorescence channel before the stroke. With it, a twin of the
+     * stroke paints the 4-channel fluorescence surface; `fluorChannel()` returns the result.
+     */
+    fluor?: {
+        surface: TiledSurface;
+    } | null;
+    /**
+     * Thermochromic ink: the layer's thermochromic channel before the stroke. With it, a twin of the
+     * stroke paints the 4-channel thermochromic surface; `thermoChannel()` returns the result.
+     */
+    thermo?: {
+        surface: TiledSurface;
+    } | null;
 }
 export interface PaintStrokeResult {
     layerId: string;
@@ -129,10 +143,18 @@ export declare class PaintStrokeSession {
     private wet;
     private readonly wetDriver;
     private thickDriver;
+    private filmBuffer;
     private stickerSpray;
     /** Light paint: the stroke's twin over the light channel, and what it left there. */
     private readonly lightTwin;
     private lightResult;
+    /** UV-fluorescent ink: the stroke's twin over the fluorescence channel, and what it left there. */
+    private readonly fluorTwin;
+    private fluorResult;
+    /** Thermochromic ink: the stroke's twin over the thermochromic channel, and what it left there. */
+    private readonly thermoTwin;
+    private thermoResult;
+    private readonly invisibleDaylight;
     /** A wet stroke that ended while the simulation was mid-batch: it commits when the driver catches up. */
     private wetEndPending;
     private readonly apply;
@@ -154,15 +176,23 @@ export declare class PaintStrokeSession {
     repaintEffect(pixels: EffectPaintPixels): void;
     /** The stroke's twin over the light channel: the same marks in grey at the brush's light amount (see `light.ts`). */
     private makeLightTwin;
+    /** The stroke's twin over the 4-channel fluorescence surface (see `heat.ts`). */
+    private makeFluorTwin;
+    /** The stroke's twin over the 4-channel thermochromic surface (see `heat.ts`). */
+    private makeThermoTwin;
     /** Light paint: the layer's light channel after the stroke, or `null` when the stroke has no twin or left it unchanged. */
     lightChannel(): TiledSurface | null;
+    /** UV-fluorescent ink: the layer's fluorescence channel after the stroke, or `null` when unchanged. */
+    fluorChannel(): TiledSurface | null;
+    /** Thermochromic ink: the layer's thermochromic channel after the stroke, or `null` when unchanged. */
+    thermoChannel(): TiledSurface | null;
     private tileTarget;
     get open(): boolean;
     /** Adds raw pen samples (document pixels). */
     push(points: readonly PenPoint[]): void;
     /** Sticker strokes: the stickers sprayed so far. */
     stickers(): Sticker[] | null;
-    /** Impasto strokes: the layer's thick-paint channels with the stroke so far. */
+    /** Impasto or iridescent strokes: the layer's thick-paint channels with the stroke so far. */
     thickChannels(): ThickChannels | null;
     /** Shows a wet stroke's progress (the wet layer's display). */
     wetUpdate(rects: RasterRect[]): void;

package/dist/paint-editor/thick.d.cts

@@ -17,6 +17,7 @@ import { type MixerLoad, type PaintTileTarget, type RgbTriple } from '../paint/e
 import { type PaintGradientSource } from '../paint/gradient-paint.cjs';
 import { type EffectPaintPixels } from './effect-paint.cjs';
 import { TiledSurface, type RasterRect } from '../raster/surface.cjs';
+import type { IridescenceSettings } from './brush-model.cjs';
 import type { PaintBrush } from './brushes.cjs';
 import { type PenPoint, type StrokeCopy } from './engine.cjs';
 /** Where the light comes from. */
@@ -30,26 +31,63 @@ export interface PaintLighting {
 }
 export declare const DEFAULT_LIGHTING: Readonly<PaintLighting>;
 export declare function normalizeLighting(raw?: Partial<PaintLighting>, base?: PaintLighting): PaintLighting;
+/** View tilt (-1..1 on each axis, default 0): shifts the view vector for thin-film iridescence and highlights, not the light. Not saved with the document. */
+export interface PaintViewTilt {
+    x: number;
+    y: number;
+}
+export declare const DEFAULT_VIEW_TILT: Readonly<PaintViewTilt>;
+export declare function normalizeViewTilt(raw?: Partial<PaintViewTilt>, base?: PaintViewTilt): PaintViewTilt;
+export declare function viewTiltKey(v: PaintViewTilt): string;
 /** A layer's thick-paint channels (layer space, like its pixels). */
 export interface ThickChannels {
     /** Height 0..255 per pixel (1 channel). */
     height: TiledSurface;
     /** Material per pixel (4 channels): R gloss, G metallic, B rim (light paint), A opacity for clarity (255 solid; 0 no material, read as solid). */
     material: TiledSurface;
+    /** Thin-film iridescence per pixel (4 channels): R thickness (0..255 → 100..1000 nm), G refractive index (0..255 → 1.2..2.0), B 0, A film coverage (0..255). */
+    film: TiledSurface;
 }
 export declare function emptyThickChannels(): ThickChannels;
+export declare function hasThickChannels(ch: ThickChannels | undefined): boolean;
+/**
+ * Thin-film interference reflectance (linear RGB 0..1) for an optical path difference `opd` in nm:
+ * Airy / cosine interference across the three primary bands (630, 532, 465 nm) with a half-wave
+ * top-surface phase shift.
+ */
+export declare function thinFilmRgb(opd: number): [number, number, number];
 export declare function lightingKey(l: PaintLighting): string;
 /**
- * One tile of a thick layer lit: `color` (RGBA, straight), the height and material of the tile, and
- * the height of its 8 neighbours for the slopes at the border (`heightAt(dx, dy)` returns the
- * neighbouring tile's data or null). Returns a new RGBA tile.
+ * One tile of a thick or iridescent layer lit: `color` (RGBA, straight), the height, material and
+ * thin-film channels of the tile, and the height of its 8 neighbours for the slopes at the border
+ * (`heightAround(dx, dy)` returns the neighbouring tile's data or null). Returns a new RGBA tile.
  */
-export declare function lightTile(color: Uint8ClampedArray, height: Uint8ClampedArray | null, heightAround: (dx: number, dy: number) => Uint8ClampedArray | null, material: Uint8ClampedArray | null, light: PaintLighting): Uint8ClampedArray;
+export declare function lightTile(color: Uint8ClampedArray, height: Uint8ClampedArray | null, heightAround: (dx: number, dy: number) => Uint8ClampedArray | null, material: Uint8ClampedArray | null, light: PaintLighting, film?: Uint8ClampedArray | null, viewTilt?: PaintViewTilt): Uint8ClampedArray;
 /** Cache of lit tiles for one layer, by the identity of their inputs. */
 export declare class LitCache {
     private readonly tiles;
-    /** The layer's pixels lit (tiles without relief nearby are the colour tiles themselves). */
-    lit(color: TiledSurface, ch: ThickChannels, light: PaintLighting): TiledSurface;
+    /** The layer's pixels lit (tiles without relief or film nearby are the colour tiles themselves). */
+    lit(color: TiledSurface, ch: ThickChannels, light: PaintLighting, viewTilt?: PaintViewTilt): TiledSurface;
+}
+/** Live thin-film iridescence buffer for any stroke engine (deposits or erases into 4-channel `ThickChannels.film`). */
+export declare class FilmBuffer {
+    private readonly base;
+    private readonly offset;
+    private readonly mask;
+    private readonly tiles;
+    constructor(base: TiledSurface, offset?: {
+        x: number;
+        y: number;
+    }, mask?: PaintTileTarget['selection']);
+    private maskAt;
+    private tile;
+    /** Deposits thin-film iridescence over `rect` with per-pixel `coverage` (0..1) scaled by `strength` (0..1). */
+    deposit(rect: RasterRect, coverage: ArrayLike<number>, strength: number, ir: IridescenceSettings, pressure?: number): void;
+    /** Stamps a soft disc of thin-film iridescence at `(cx, cy)` (document pixels) with `radius` and `alpha` (0..1). */
+    stampDisc(cx: number, cy: number, radius: number, alpha: number, ir: IridescenceSettings, pressure?: number): void;
+    /** Erases thin-film coverage over `rect` by `coverage[p] * strength`. */
+    erase(rect: RasterRect, coverage: ArrayLike<number>, strength: number): void;
+    surface(): TiledSurface;
 }
 export interface ThickStrokeInit {
     brush: PaintBrush;
@@ -76,6 +114,7 @@ export declare class ThickStrokeDriver {
     private readonly medium;
     private readonly height;
     private readonly material;
+    private readonly film;
     private readonly paint;
     private readonly centre;
     private tip;
@@ -119,8 +158,10 @@ export interface SavedThickChannels {
     height: string;
     /** RGBA PNG of the material (R gloss, G metallic). */
     material: string;
+    /** RGBA PNG of the thin-film iridescence (R thickness, G refractive index, A coverage), when any. */
+    film?: string;
 }
-/** Channels → saved form (`null` when there is no relief). */
+/** Channels → saved form (`null` when there is neither relief nor film). */
 export declare function thickToJSON(ch: ThickChannels): SavedThickChannels | null;
 /** Saved form → channels; throws a sentence when it cannot be read. */
 export declare function thickFromJSON(raw: unknown): ThickChannels;

package/dist/paint-editor/thick.d.ts

@@ -17,6 +17,7 @@ import { type MixerLoad, type PaintTileTarget, type RgbTriple } from '../paint/e
 import { type PaintGradientSource } from '../paint/gradient-paint.js';
 import { type EffectPaintPixels } from './effect-paint.js';
 import { TiledSurface, type RasterRect } from '../raster/surface.js';
+import type { IridescenceSettings } from './brush-model.js';
 import type { PaintBrush } from './brushes.js';
 import { type PenPoint, type StrokeCopy } from './engine.js';
 /** Where the light comes from. */
@@ -30,26 +31,63 @@ export interface PaintLighting {
 }
 export declare const DEFAULT_LIGHTING: Readonly<PaintLighting>;
 export declare function normalizeLighting(raw?: Partial<PaintLighting>, base?: PaintLighting): PaintLighting;
+/** View tilt (-1..1 on each axis, default 0): shifts the view vector for thin-film iridescence and highlights, not the light. Not saved with the document. */
+export interface PaintViewTilt {
+    x: number;
+    y: number;
+}
+export declare const DEFAULT_VIEW_TILT: Readonly<PaintViewTilt>;
+export declare function normalizeViewTilt(raw?: Partial<PaintViewTilt>, base?: PaintViewTilt): PaintViewTilt;
+export declare function viewTiltKey(v: PaintViewTilt): string;
 /** A layer's thick-paint channels (layer space, like its pixels). */
 export interface ThickChannels {
     /** Height 0..255 per pixel (1 channel). */
     height: TiledSurface;
     /** Material per pixel (4 channels): R gloss, G metallic, B rim (light paint), A opacity for clarity (255 solid; 0 no material, read as solid). */
     material: TiledSurface;
+    /** Thin-film iridescence per pixel (4 channels): R thickness (0..255 → 100..1000 nm), G refractive index (0..255 → 1.2..2.0), B 0, A film coverage (0..255). */
+    film: TiledSurface;
 }
 export declare function emptyThickChannels(): ThickChannels;
+export declare function hasThickChannels(ch: ThickChannels | undefined): boolean;
+/**
+ * Thin-film interference reflectance (linear RGB 0..1) for an optical path difference `opd` in nm:
+ * Airy / cosine interference across the three primary bands (630, 532, 465 nm) with a half-wave
+ * top-surface phase shift.
+ */
+export declare function thinFilmRgb(opd: number): [number, number, number];
 export declare function lightingKey(l: PaintLighting): string;
 /**
- * One tile of a thick layer lit: `color` (RGBA, straight), the height and material of the tile, and
- * the height of its 8 neighbours for the slopes at the border (`heightAt(dx, dy)` returns the
- * neighbouring tile's data or null). Returns a new RGBA tile.
+ * One tile of a thick or iridescent layer lit: `color` (RGBA, straight), the height, material and
+ * thin-film channels of the tile, and the height of its 8 neighbours for the slopes at the border
+ * (`heightAround(dx, dy)` returns the neighbouring tile's data or null). Returns a new RGBA tile.
  */
-export declare function lightTile(color: Uint8ClampedArray, height: Uint8ClampedArray | null, heightAround: (dx: number, dy: number) => Uint8ClampedArray | null, material: Uint8ClampedArray | null, light: PaintLighting): Uint8ClampedArray;
+export declare function lightTile(color: Uint8ClampedArray, height: Uint8ClampedArray | null, heightAround: (dx: number, dy: number) => Uint8ClampedArray | null, material: Uint8ClampedArray | null, light: PaintLighting, film?: Uint8ClampedArray | null, viewTilt?: PaintViewTilt): Uint8ClampedArray;
 /** Cache of lit tiles for one layer, by the identity of their inputs. */
 export declare class LitCache {
     private readonly tiles;
-    /** The layer's pixels lit (tiles without relief nearby are the colour tiles themselves). */
-    lit(color: TiledSurface, ch: ThickChannels, light: PaintLighting): TiledSurface;
+    /** The layer's pixels lit (tiles without relief or film nearby are the colour tiles themselves). */
+    lit(color: TiledSurface, ch: ThickChannels, light: PaintLighting, viewTilt?: PaintViewTilt): TiledSurface;
+}
+/** Live thin-film iridescence buffer for any stroke engine (deposits or erases into 4-channel `ThickChannels.film`). */
+export declare class FilmBuffer {
+    private readonly base;
+    private readonly offset;
+    private readonly mask;
+    private readonly tiles;
+    constructor(base: TiledSurface, offset?: {
+        x: number;
+        y: number;
+    }, mask?: PaintTileTarget['selection']);
+    private maskAt;
+    private tile;
+    /** Deposits thin-film iridescence over `rect` with per-pixel `coverage` (0..1) scaled by `strength` (0..1). */
+    deposit(rect: RasterRect, coverage: ArrayLike<number>, strength: number, ir: IridescenceSettings, pressure?: number): void;
+    /** Stamps a soft disc of thin-film iridescence at `(cx, cy)` (document pixels) with `radius` and `alpha` (0..1). */
+    stampDisc(cx: number, cy: number, radius: number, alpha: number, ir: IridescenceSettings, pressure?: number): void;
+    /** Erases thin-film coverage over `rect` by `coverage[p] * strength`. */
+    erase(rect: RasterRect, coverage: ArrayLike<number>, strength: number): void;
+    surface(): TiledSurface;
 }
 export interface ThickStrokeInit {
     brush: PaintBrush;
@@ -76,6 +114,7 @@ export declare class ThickStrokeDriver {
     private readonly medium;
     private readonly height;
     private readonly material;
+    private readonly film;
     private readonly paint;
     private readonly centre;
     private tip;
@@ -119,8 +158,10 @@ export interface SavedThickChannels {
     height: string;
     /** RGBA PNG of the material (R gloss, G metallic). */
     material: string;
+    /** RGBA PNG of the thin-film iridescence (R thickness, G refractive index, A coverage), when any. */
+    film?: string;
 }
-/** Channels → saved form (`null` when there is no relief). */
+/** Channels → saved form (`null` when there is neither relief nor film). */
 export declare function thickToJSON(ch: ThickChannels): SavedThickChannels | null;
 /** Saved form → channels; throws a sentence when it cannot be read. */
 export declare function thickFromJSON(raw: unknown): ThickChannels;

package/dist/paint-editor/ui.d.cts

@@ -156,7 +156,7 @@ export declare function guideOverlay(controller: PaintEditorController, drag?: {
     to: Point2;
     kind: GuideOverlayKind;
 }>;
-export { BRUSH_SLIDERS, brushEngineControls, GHOST_SLIDERS, multiColorSliders, patchBrushValue, type BrushEngineControls, type SliderControl } from './brush-controls.cjs';
+export { BRUSH_SLIDERS, brushEngineControls, GHOST_SLIDERS, IRIDESCENCE_SLIDERS, multiColorSliders, MUTATION_SLIDERS, patchBrushValue, type BrushEngineControls, type SliderControl } from './brush-controls.cjs';
 import type { SliderControl } from './brush-controls.cjs';
 export declare const PAPER_SLIDERS: readonly SliderControl[];
 /** Reads `a.b` from an object. */
@@ -230,6 +230,39 @@ export declare const WET_MEDIUM_LABELS: Readonly<Record<WetMediumKind, string>>;
 export declare const IMPASTO_TOOL_LABELS: Readonly<Record<ImpastoTool, string>>;
 /** The light sliders (thick paint and metallic paper). */
 export declare const LIGHT_SLIDERS: readonly SliderControl[];
+/** The UV blacklight sliders. */
+export declare const UV_LIGHT_SLIDERS: readonly SliderControl[];
+/** The view tilt sliders (thin-film iridescence and specular highlights). */
+export declare const VIEW_TILT_SLIDERS: readonly SliderControl[];
+/**
+ * Maps `DeviceOrientationEvent` angles (`beta` front-to-back in degrees, `gamma` left-to-right in
+ * degrees) relative to `rest` (default `{ beta: 45, gamma: 0 }`, a tablet held in hand) into a
+ * `viewTilt` in `-1..1` (35° reaches full tilt), rounded to 0.01.
+ */
+export declare function deviceOrientationToViewTilt(betaOrEvent: number | {
+    beta?: number | null;
+    gamma?: number | null;
+} | null | undefined, gammaOrRest?: number | {
+    beta: number;
+    gamma: number;
+} | null | undefined, rest?: {
+    beta: number;
+    gamma: number;
+}): {
+    x: number;
+    y: number;
+};
+/**
+ * Asks iOS Safari for `DeviceOrientationEvent` permission when `requestPermission` is present
+ * (must be called from a user gesture on iOS 13+). Resolves to `'granted'` on browsers that do not
+ * gate `deviceorientation` behind a permission prompt, or `'unsupported'` without `DeviceOrientationEvent`.
+ */
+export declare function requestDeviceTiltPermission(): Promise<'granted' | 'denied' | 'unsupported'>;
+/**
+ * Listens to `deviceorientation` events on `globalThis` and updates `controller.setViewTilt` relative
+ * to the first reading's orientation. Returns a cleanup function.
+ */
+export declare function startDeviceTilt(controller: PaintEditorController): () => void;
 /** Labels of the particle kinds and renders. */
 export declare const PARTICLE_KIND_LABELS: Readonly<Record<ParticleKind, string>>;
 export declare const PARTICLE_RENDER_LABELS: Readonly<Record<ParticleRender, string>>;