@pixerate/editor 0.241.0 → 0.243.0

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

@@ -0,0 +1,74 @@
+/**
+ * Light paint: a per-layer light channel (`doc.light`, one channel 0..255 per pixel, in layer
+ * space like the thick-paint channels) saying how much light the paint there gives off. The
+ * light's colour is the layer's own colour at that pixel, so recolouring the paint recolours its
+ * light.
+ *
+ * Laying and moving light: a stroke on a layer with light (or with a brush that lays it) runs a
+ * twin of itself over the light channel drawn as grey paint (`lightToShadow`: white with alpha =
+ * light). The twin uses the same engine, seed and points with the brush's light amount as its grey
+ * colour, in a normal blend and RGB mixing, so light is laid by exactly the stroke's coverage,
+ * plain paint over glowing paint dims it, erasers take it away, and smudges, blenders, the knife,
+ * the Mixer Brush and pick-up brushes move and pick up light as they move colour.
+ *
+ * Rendering: glow adds `light × colour × GLOW` (linear light) to the layer's own pixels; spill
+ * blurs `light × colour` outwards (at a reduced resolution) into its own layer drawn directly above
+ * with Linear Dodge (Add). Impasto rim (material B) brightens a bead's light where its surface
+ * turns away, and clarity (material A) lets the middle of a bead show the layers below.
+ */
+import { TiledSurface, type RasterRect } from '../raster/surface.cjs';
+import { type PaintBrush } from './brushes.cjs';
+import type { ThickChannels } from './thick.cjs';
+/** How much brighter full light makes the paint itself (linear light). */
+export declare const GLOW = 1.5;
+/** A layer's spill: how far its light reaches (px; 0 turns spill off) and how strong it is (0..2). */
+export interface LightSpill {
+    radius: number;
+    strength: number;
+}
+export declare const DEFAULT_LIGHT_SPILL: Readonly<LightSpill>;
+/** Checks and fills a spill change; throws a sentence naming the bad field. */
+export declare function normalizeLightSpill(raw: Partial<LightSpill>, base?: LightSpill): LightSpill;
+export declare function emptyLight(): TiledSurface;
+/** The light channel as grey paint for a stroke's twin: white, with alpha = light. */
+export declare function lightToShadow(light: TiledSurface): TiledSurface;
+/** A twin's grey paint back as light: grey × alpha. */
+export declare function shadowToLight(shadow: TiledSurface): TiledSurface;
+/** The brush a stroke's light twin paints with: the same marks, grey, normal blend, RGB mixing, no gradient. */
+export declare function lightTwinBrush(brush: PaintBrush): PaintBrush;
+/** Where a layer's light is (layer space) and its brightest value 0..255; `null` bounds when it has none. */
+export declare function lightInfo(light: TiledSurface | undefined): {
+    bounds: RasterRect | null;
+    peak: number;
+};
+/** Light scaled by `k` (0..1), e.g. under a fill that covers it. */
+export declare function scaleLight(light: TiledSurface, k: number): TiledSurface;
+/**
+ * Light of a layer merged down onto the one below (both in the lower layer's space): the upper
+ * layer's light over the lower's, which shows through where the upper paint is transparent.
+ */
+export declare function mergeLight(lower: TiledSurface | undefined, upper: TiledSurface | undefined, upperColor: TiledSurface): TiledSurface | undefined;
+/**
+ * Glow, rim and clarity over a layer's (lit) colour, tile by tile, cached by the identity of each
+ * tile's inputs. Tiles with no light and no clear thick paint are the colour tiles themselves.
+ */
+export declare class LightCache {
+    private readonly tiles;
+    glow(color: TiledSurface, light: TiledSurface | undefined, thick: ThickChannels | undefined): TiledSurface;
+    private spillCache;
+    /**
+     * The layer's spill (layer space, RGBA for Linear Dodge (Add)): `light × colour` blurred by
+     * `radius` px at a reduced resolution, times `strength`; `null` without light or spill.
+     */
+    spill(color: TiledSurface, light: TiledSurface | undefined, spill: LightSpill): TiledSurface | null;
+}
+/** See `LightCache.spill`. */
+export declare function computeSpill(color: TiledSurface, light: TiledSurface | undefined, spill: LightSpill): TiledSurface | null;
+/** A layer's light as saved: its rect (layer space) and a grey PNG. */
+export interface SavedLight {
+    rect: RasterRect;
+    light: string;
+}
+export declare function lightToJSON(light: TiledSurface): SavedLight | null;
+/** Saved form → light channel; throws a sentence when it cannot be read. */
+export declare function lightFromJSON(raw: unknown): TiledSurface;

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

@@ -0,0 +1,74 @@
+/**
+ * Light paint: a per-layer light channel (`doc.light`, one channel 0..255 per pixel, in layer
+ * space like the thick-paint channels) saying how much light the paint there gives off. The
+ * light's colour is the layer's own colour at that pixel, so recolouring the paint recolours its
+ * light.
+ *
+ * Laying and moving light: a stroke on a layer with light (or with a brush that lays it) runs a
+ * twin of itself over the light channel drawn as grey paint (`lightToShadow`: white with alpha =
+ * light). The twin uses the same engine, seed and points with the brush's light amount as its grey
+ * colour, in a normal blend and RGB mixing, so light is laid by exactly the stroke's coverage,
+ * plain paint over glowing paint dims it, erasers take it away, and smudges, blenders, the knife,
+ * the Mixer Brush and pick-up brushes move and pick up light as they move colour.
+ *
+ * Rendering: glow adds `light × colour × GLOW` (linear light) to the layer's own pixels; spill
+ * blurs `light × colour` outwards (at a reduced resolution) into its own layer drawn directly above
+ * with Linear Dodge (Add). Impasto rim (material B) brightens a bead's light where its surface
+ * turns away, and clarity (material A) lets the middle of a bead show the layers below.
+ */
+import { TiledSurface, type RasterRect } from '../raster/surface.js';
+import { type PaintBrush } from './brushes.js';
+import type { ThickChannels } from './thick.js';
+/** How much brighter full light makes the paint itself (linear light). */
+export declare const GLOW = 1.5;
+/** A layer's spill: how far its light reaches (px; 0 turns spill off) and how strong it is (0..2). */
+export interface LightSpill {
+    radius: number;
+    strength: number;
+}
+export declare const DEFAULT_LIGHT_SPILL: Readonly<LightSpill>;
+/** Checks and fills a spill change; throws a sentence naming the bad field. */
+export declare function normalizeLightSpill(raw: Partial<LightSpill>, base?: LightSpill): LightSpill;
+export declare function emptyLight(): TiledSurface;
+/** The light channel as grey paint for a stroke's twin: white, with alpha = light. */
+export declare function lightToShadow(light: TiledSurface): TiledSurface;
+/** A twin's grey paint back as light: grey × alpha. */
+export declare function shadowToLight(shadow: TiledSurface): TiledSurface;
+/** The brush a stroke's light twin paints with: the same marks, grey, normal blend, RGB mixing, no gradient. */
+export declare function lightTwinBrush(brush: PaintBrush): PaintBrush;
+/** Where a layer's light is (layer space) and its brightest value 0..255; `null` bounds when it has none. */
+export declare function lightInfo(light: TiledSurface | undefined): {
+    bounds: RasterRect | null;
+    peak: number;
+};
+/** Light scaled by `k` (0..1), e.g. under a fill that covers it. */
+export declare function scaleLight(light: TiledSurface, k: number): TiledSurface;
+/**
+ * Light of a layer merged down onto the one below (both in the lower layer's space): the upper
+ * layer's light over the lower's, which shows through where the upper paint is transparent.
+ */
+export declare function mergeLight(lower: TiledSurface | undefined, upper: TiledSurface | undefined, upperColor: TiledSurface): TiledSurface | undefined;
+/**
+ * Glow, rim and clarity over a layer's (lit) colour, tile by tile, cached by the identity of each
+ * tile's inputs. Tiles with no light and no clear thick paint are the colour tiles themselves.
+ */
+export declare class LightCache {
+    private readonly tiles;
+    glow(color: TiledSurface, light: TiledSurface | undefined, thick: ThickChannels | undefined): TiledSurface;
+    private spillCache;
+    /**
+     * The layer's spill (layer space, RGBA for Linear Dodge (Add)): `light × colour` blurred by
+     * `radius` px at a reduced resolution, times `strength`; `null` without light or spill.
+     */
+    spill(color: TiledSurface, light: TiledSurface | undefined, spill: LightSpill): TiledSurface | null;
+}
+/** See `LightCache.spill`. */
+export declare function computeSpill(color: TiledSurface, light: TiledSurface | undefined, spill: LightSpill): TiledSurface | null;
+/** A layer's light as saved: its rect (layer space) and a grey PNG. */
+export interface SavedLight {
+    rect: RasterRect;
+    light: string;
+}
+export declare function lightToJSON(light: TiledSurface): SavedLight | null;
+/** Saved form → light channel; throws a sentence when it cannot be read. */
+export declare function lightFromJSON(raw: unknown): TiledSurface;

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

@@ -85,6 +85,13 @@ export interface StrokeSessionInit {
         source: PaintEffectPaint;
         pixels: EffectPaintPixels;
     } | null;
+    /**
+     * Light paint: the layer's light channel before the stroke. With it, a twin of the stroke paints
+     * the light channel as grey (see `light.ts`); `lightChannel()` returns the result.
+     */
+    light?: {
+        surface: TiledSurface;
+    } | null;
 }
 export interface PaintStrokeResult {
     layerId: string;
@@ -113,6 +120,9 @@ export declare class PaintStrokeSession {
     private readonly wetDriver;
     private readonly thickDriver;
     private readonly stickerSpray;
+    /** Light paint: the stroke's twin over the light channel, and what it left there. */
+    private readonly lightTwin;
+    private lightResult;
     /** A wet stroke that ended while the simulation was mid-batch: it commits when the driver catches up. */
     private wetEndPending;
     private readonly apply;
@@ -124,6 +134,10 @@ export declare class PaintStrokeSession {
     /** The mask stencils this stroke was painted with when they are not the editor's (replays). */
     maskStencils: readonly import('./stencils.cjs').Stencil[] | null;
     constructor(host: StrokeSessionHost, init: StrokeSessionInit);
+    /** The stroke's twin over the light channel: the same marks in grey at the brush's light amount (see `light.ts`). */
+    private makeLightTwin;
+    /** 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;
     private tileTarget;
     get open(): boolean;
     /** Adds raw pen samples (document pixels). */

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

@@ -85,6 +85,13 @@ export interface StrokeSessionInit {
         source: PaintEffectPaint;
         pixels: EffectPaintPixels;
     } | null;
+    /**
+     * Light paint: the layer's light channel before the stroke. With it, a twin of the stroke paints
+     * the light channel as grey (see `light.ts`); `lightChannel()` returns the result.
+     */
+    light?: {
+        surface: TiledSurface;
+    } | null;
 }
 export interface PaintStrokeResult {
     layerId: string;
@@ -113,6 +120,9 @@ export declare class PaintStrokeSession {
     private readonly wetDriver;
     private readonly thickDriver;
     private readonly stickerSpray;
+    /** Light paint: the stroke's twin over the light channel, and what it left there. */
+    private readonly lightTwin;
+    private lightResult;
     /** A wet stroke that ended while the simulation was mid-batch: it commits when the driver catches up. */
     private wetEndPending;
     private readonly apply;
@@ -124,6 +134,10 @@ export declare class PaintStrokeSession {
     /** The mask stencils this stroke was painted with when they are not the editor's (replays). */
     maskStencils: readonly import('./stencils.js').Stencil[] | null;
     constructor(host: StrokeSessionHost, init: StrokeSessionInit);
+    /** The stroke's twin over the light channel: the same marks in grey at the brush's light amount (see `light.ts`). */
+    private makeLightTwin;
+    /** 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;
     private tileTarget;
     get open(): boolean;
     /** Adds raw pen samples (document pixels). */

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

@@ -1,7 +1,7 @@
 /**
  * Agent tools for thick paint and light: impasto strokes are painted with `paint_stroke` and an
- * impasto brush; these tools move the light, read and flatten a layer's relief, and switch instant
- * drying of wet strokes.
+ * impasto brush; these tools move the light, read and flatten a layer's relief, read, spill and
+ * clear light paint, and switch instant drying of wet strokes.
  */
 import type { PaintAgentTool } from './hosted.cjs';
 import type { PaintEditorController } from './controller.cjs';

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

@@ -1,7 +1,7 @@
 /**
  * Agent tools for thick paint and light: impasto strokes are painted with `paint_stroke` and an
- * impasto brush; these tools move the light, read and flatten a layer's relief, and switch instant
- * drying of wet strokes.
+ * impasto brush; these tools move the light, read and flatten a layer's relief, read, spill and
+ * clear light paint, and switch instant drying of wet strokes.
  */
 import type { PaintAgentTool } from './hosted.js';
 import type { PaintEditorController } from './controller.js';

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

@@ -34,7 +34,7 @@ export declare function normalizeLighting(raw?: Partial<PaintLighting>, base?: P
 export interface ThickChannels {
     /** Height 0..255 per pixel (1 channel). */
     height: TiledSurface;
-    /** Material per pixel (4 channels): R gloss, G metallic, B and A unused. */
+    /** 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;
 }
 export declare function emptyThickChannels(): ThickChannels;
@@ -100,6 +100,10 @@ export declare class ThickStrokeDriver {
     private dab;
     /** The knife: flattens the relief under it and carries some of it along (a patch, like a smudge). */
     private knifeHeight;
+    /**
+     * Material: R gloss, G metallic, B rim (light paint, 0..255), A opacity for light paint's clarity
+     * (255 solid .. 1 clearest; 0 is no material, read as solid).
+     */
     private paintMaterial;
 }
 /** Height statistics of a layer's relief (for tools). */

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

@@ -34,7 +34,7 @@ export declare function normalizeLighting(raw?: Partial<PaintLighting>, base?: P
 export interface ThickChannels {
     /** Height 0..255 per pixel (1 channel). */
     height: TiledSurface;
-    /** Material per pixel (4 channels): R gloss, G metallic, B and A unused. */
+    /** 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;
 }
 export declare function emptyThickChannels(): ThickChannels;
@@ -100,6 +100,10 @@ export declare class ThickStrokeDriver {
     private dab;
     /** The knife: flattens the relief under it and carries some of it along (a patch, like a smudge). */
     private knifeHeight;
+    /**
+     * Material: R gloss, G metallic, B rim (light paint, 0..255), A opacity for light paint's clarity
+     * (255 solid .. 1 clearest; 0 is no material, read as solid).
+     */
     private paintMaterial;
 }
 /** Height statistics of a layer's relief (for tools). */

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

@@ -193,6 +193,8 @@ export interface BrushEngineControls {
     particleMenus?: boolean;
     /** The sticker stamp toggles (`sticker.stamps`, `STAMP_KINDS`). */
     stickerStamps?: boolean;
+    /** Light paint: the "light follows pressure" toggle (`light.pressure`); the Light slider is in `sliders`. */
+    light?: boolean;
 }
 /**
  * The controls the active brush's engine adds to the brush panel (`null` for the eraser):

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

@@ -193,6 +193,8 @@ export interface BrushEngineControls {
     particleMenus?: boolean;
     /** The sticker stamp toggles (`sticker.stamps`, `STAMP_KINDS`). */
     stickerStamps?: boolean;
+    /** Light paint: the "light follows pressure" toggle (`light.pressure`); the Light slider is in `sliders`. */
+    light?: boolean;
 }
 /**
  * The controls the active brush's engine adds to the brush panel (`null` for the eraser):