Electric textures

Read as Markdown

These TypeScript recipes from @pibbl/core/textures use the public resource-backed defineTexture lifecycle. Mount with useTexture, use the handle in style.fill or style.stroke, and send typed commands outside component evaluation. Paint views share source pixels and lifetime within the owning Pibbl tree.

ElectricControl

Both resources accept { type: "pause", paused } and { type: "reset", seed? }. Reset clears contacts and time, preserves pause and visual controls, and optionally selects another seed. Reproduction requires the same configuration, frame deltas, and command history; pixel antialiasing can vary by browser. No arbitrary-time seek or replay checkpoint is provided.

ElectricOptions

seed selects seeded geometry; branching is 0..1 and glow is 0..2. Glow changes halo strokes without widening the white core. Leave space around paths: texture and shape boundaries still clip pixels. The globe reserves 10% per side.

ElectricPoint

{ x, y } uses normalized 0..1 texture coordinates, including padding. Map Pibbl root-logical pointer coordinates into the fill placement in application code.

ElectricSource

A structured-cloneable { id, point, weight } attachment site in normalized texture coordinates. IDs are unique strings of 1..128 characters; weights are finite 0..1,000,000. Zero disables a site. At most 512 sites may be active. Weights control seeded selection preference, brightness, and terminal crackle size. There is no special pointer site: input adds an ordinary high-weight source.

ElectricSourceMessage

upsert-source accepts one source; remove-source accepts its id. set-sources replaces the collection and reset baseline atomically. Reordering sites does not affect seeded selection. Moving a site with the same ID preserves connections and approaches the new point smoothly. Reset removes transient upserts and restores the latest baseline supplied by configuration or set-sources.

lightning

lightning(options?) creates branching connections with persistent coarse shape, fast flicker, and optional edge destinations. Positive and negative are artistic source/destination names. The Plasma Globe shows an independent lightning preview alongside its weighted tendrils; weighted sources control the tendrils’ own terminal crackles.

LightningMessage

connect takes a string id, positive, and negative; sending the same id moves that connection. disconnect fades it out. Up to 24 manual connections are retained. configure changes source, destination, edge, active state, branching, glow, or frequency. Contact glow, when enabled, appears at each source.

Both effects cap admitted frame time at 50 ms and use Pibbl’s scheduler. Pause stops continuing frame requests; commands can still change paused output. Resolution belongs to useTexture and is independent of display size. The Plasma Globe uses two 320 × 320 resources shared across all its consumers.

LightningOptions

Adds positive, negative, optional edge (top, right, bottom, left), active (default true), frequency (1..30 topology refreshes per second, default 15), and contactCore (default false). Edge mode chooses an inset negative point and changes it every six flickers. active: false disables only the configured connection, allowing a texture of manually supplied connections.

tendrils

tendrils(options?) creates slow wandering filaments between weighted sites and a common electrode with transparent surroundings. It is independent of globe presentation and pointer handling.

TendrilsMessage

Accepts ElectricSourceMessage, pause/reset, and configure for branching, glow, rise, crackle, or frequency. High-weight sources attract more persistent filaments; no source is guaranteed a fixed number. Every source uses the same selection rule. Sources choose birth locations. Endpoints then rise continuously instead of hopping to other sites. Weight resists convection by scaling upward speed with 1 / (1 + weight²), so heavy contacts hold filaments nearly stationary. Removing a site preserves its endpoints: they continue upward and fade within five seconds before rebirth. No old idle endpoint is restored. Pibbl shapes still clip pixels; an optional boundary guides endpoints along the vessel edge.

TendrilsOptions

Adds sources (default empty), center (the common electrode, default 0.5,0.5), count (integer 1..32, default 15), rise (0..1, default 0), crackle (0..1, default 0), and frequency (1..30 crackle refreshes/second, default 18). There is no implicit circular geometry or perimeter/interior mode. Supply shape outline samples and interior points together as ordinary weighted sources. Optional boundary supplies 3..256 normalized points forming one simple closed polygon. Rising endpoints stop at it and follow upward edges, holding at local peaks until rebirth. Omit it for free drift. This guides endpoints, not full branch collision physics; use the same path for clipping the fill. The Plasma Globe derives its sites from PathGeometry using flattenPath and even arc-length sampling; its source overlay displays the data.

API details from source

tendrils

Weighted attachment sites and persistent filaments, independent of vessel geometry.

tendrils: (config?: TendrilsOptions) => TextureRecipe<TendrilsMessage>

Parameters

config — Tendril motion and appearance settings. See TendrilsOptions.

Returns

A tendril texture recipe for useTexture.

TendrilsOptions

Electrical appearance, source electrodes, boundary, rise, and discharge controls for tendrils.

interface TendrilsOptions extends ElectricOptions

Related API: TendrilsOptions, ElectricOptions.

Properties and methods

seed (optional)

readonly seed?: number | undefined

Seed used for deterministic sampling or simulation initialization. See ElectricOptions .

View source — packages/core/src/features/textures/lib/electric-shared.ts:38

branching (optional)

readonly branching?: number | undefined

0..1, controls the number of secondary branches.

View source — packages/core/src/features/textures/lib/electric-shared.ts:40

glow (optional)

readonly glow?: number | undefined

0..2, scales the soft halo without widening the white core.

View source — packages/core/src/features/textures/lib/electric-shared.ts:42

center (optional)

readonly center?: ElectricPoint | undefined

Related API: ElectricPoint.

Common electrode. Sources seed the outer endpoints.

View source — packages/core/src/features/textures/lib/tendrils.ts:37

sources (optional)

readonly sources?: readonly ElectricSource[] | undefined

Related API: ElectricSource.

Named electrical source electrodes. See ElectricSource.

View source — packages/core/src/features/textures/lib/tendrils.ts:39

boundary (optional)

readonly boundary?: readonly ElectricPoint[] | undefined

Related API: ElectricPoint.

Optional simple closed vessel outline in normalized texture coordinates.

View source — packages/core/src/features/textures/lib/tendrils.ts:41

count (optional)

readonly count?: number | undefined

Number of particles or sources requested by this configuration. See TendrilsOptions.

View source — packages/core/src/features/textures/lib/tendrils.ts:45

rise (optional)

readonly rise?: number | undefined

Continuous upward drift speed, 0..1. No circular boundary is assumed.

View source — packages/core/src/features/textures/lib/tendrils.ts:47

crackle (optional)

readonly crackle?: number | undefined

Terminal discharge size, 0..1. Source weight also scales the discharge.

View source — packages/core/src/features/textures/lib/tendrils.ts:49

frequency (optional)

readonly frequency?: number | undefined

Rate at which the pattern or motion repeats. See TendrilsOptions.

View source — packages/core/src/features/textures/lib/tendrils.ts:51

TendrilsMessage

Control, source-editing, and live appearance commands for a tendrils texture.

Full type declaration

type TendrilsMessage = | ElectricControl
  | ElectricSourceMessage
  | {
      /** The literal "configure" identifying this variant. See {@link TendrilsMessage}. */
      readonly type: "configure";
      /** Amount of secondary electrical branching. See {@link TendrilsMessage}. */
      readonly branching?: number;
      /** Intensity of the electrical halo around the core. See {@link TendrilsMessage}. */
      readonly glow?: number;
      /** Upward drift strength of the tendrils. See {@link TendrilsMessage}. */
      readonly rise?: number;
      /** Intensity of terminal discharges. See {@link TendrilsMessage}. */
      readonly crackle?: number;
      /** Rate at which the pattern or motion repeats. See {@link TendrilsMessage}. */
      readonly frequency?: number;
    }

Properties and methods

type

readonly type: "configure" | "pause" | "remove-source" | "reset" | "set-sources" | "upsert-source"

The literal “upsert-source” identifying this variant. See ElectricSourceMessage. The literal “remove-source” identifying this variant. See ElectricSourceMessage. The literal “set-sources” identifying this variant. See ElectricSourceMessage. The literal “pause” identifying this variant. See ElectricControl. The literal “reset” identifying this variant. See ElectricControl. The literal “configure” identifying this variant. See TendrilsMessage.

View source — packages/core/src/features/textures/lib/electric-sources.ts:28

lightning

Persistent branching arcs between artistic positive/negative points.

lightning: (config?: LightningOptions) => TextureRecipe<LightningMessage>

Parameters

config — Lightning geometry, timing, and appearance settings. See LightningOptions .

Returns

A lightning texture recipe for useTexture.

LightningOptions

Electrical appearance, electrode positions, topology frequency, and base-connection controls.

interface LightningOptions extends ElectricOptions

Related API: LightningOptions, ElectricOptions.

Properties and methods

positive (optional)

readonly positive?: ElectricPoint | undefined

Related API: ElectricPoint.

Position of the positive electrode. See ElectricPoint.

View source — packages/core/src/features/textures/lib/lightning.ts:26

negative (optional)

readonly negative?: ElectricPoint | undefined

Related API: ElectricPoint.

Position of the negative electrode. See ElectricPoint.

View source — packages/core/src/features/textures/lib/lightning.ts:28

edge (optional)

readonly edge?: "bottom" | "left" | "right" | "top" | undefined

Boundary edge used as the electrical connection’s origin. See LightningOptions.

View source — packages/core/src/features/textures/lib/lightning.ts:30

active (optional)

readonly active?: boolean | undefined

Enables the configured base connection; manual connections remain independent.

View source — packages/core/src/features/textures/lib/lightning.ts:32

frequency (optional)

readonly frequency?: number | undefined

Topology refreshes per second, 1..30. Connections survive several refreshes.

View source — packages/core/src/features/textures/lib/lightning.ts:34

contactCore (optional)

readonly contactCore?: boolean | undefined

Whether to draw the electrode contact core. See LightningOptions.

View source — packages/core/src/features/textures/lib/lightning.ts:36

seed (optional)

readonly seed?: number | undefined

Seed used for deterministic sampling or simulation initialization. See ElectricOptions .

View source — packages/core/src/features/textures/lib/electric-shared.ts:38

branching (optional)

readonly branching?: number | undefined

0..1, controls the number of secondary branches.

View source — packages/core/src/features/textures/lib/electric-shared.ts:40

glow (optional)

readonly glow?: number | undefined

0..2, scales the soft halo without widening the white core.

View source — packages/core/src/features/textures/lib/electric-shared.ts:42

LightningMessage

Control, connection management, and live configuration commands for a lightning texture.

Full type declaration

type LightningMessage = | ElectricControl
  | {
      /** The literal "connect" identifying this variant. See {@link LightningMessage}. */
      readonly type: "connect";
      /** Stable identifier of this resource or connection. See {@link LightningMessage}. */
      readonly id: string;
      /** Position of the positive electrode. See {@link ElectricPoint}. */
      readonly positive: ElectricPoint;
      /** Position of the negative electrode. See {@link ElectricPoint}. */
      readonly negative: ElectricPoint;
    }
  | {
      /** The literal "disconnect" identifying this variant. See {@link LightningMessage}. */
      readonly type: "disconnect";
      /** Stable identifier of this resource or connection. See {@link LightningMessage}. */
      readonly id: string;
    }
  | {
      /** The literal "configure" identifying this variant. See {@link LightningMessage}. */
      readonly type: "configure";
      /** Position of the positive electrode. See {@link ElectricPoint}. */
      readonly positive?: ElectricPoint;
      /** Position of the negative electrode. See {@link ElectricPoint}. */
      readonly negative?: ElectricPoint;
      /** Boundary edge used as the electrical connection's origin. See {@link LightningOptions}. */
      readonly edge?: LightningOptions["edge"];
      /** Current active operation or its presentation configuration. See {@link LightningMessage}. */
      readonly active?: boolean;
      /** Amount of secondary electrical branching. See {@link LightningMessage}. */
      readonly branching?: number;
      /** Intensity of the electrical halo around the core. See {@link LightningMessage}. */
      readonly glow?: number;
      /** Rate at which the pattern or motion repeats. See {@link LightningMessage}. */
      readonly frequency?: number;
    }

Properties and methods

type

readonly type: "configure" | "connect" | "disconnect" | "pause" | "reset"

The literal “connect” identifying this variant. See LightningMessage. The literal “disconnect” identifying this variant. See LightningMessage. The literal “configure” identifying this variant. See LightningMessage. The literal “pause” identifying this variant. See ElectricControl. The literal “reset” identifying this variant. See ElectricControl.

View source — packages/core/src/features/textures/lib/lightning.ts:49

ElectricPoint

Coordinates are normalized to the complete texture, including its halo padding.

interface ElectricPoint

Related API: ElectricPoint.

Properties and methods

readonly x: number

Horizontal coordinate or displacement in the containing coordinate system. See ElectricPoint.

View source — packages/core/src/features/textures/lib/electric-shared.ts:20

readonly y: number

Vertical coordinate or displacement in the containing coordinate system. See ElectricPoint.

View source — packages/core/src/features/textures/lib/electric-shared.ts:25

ElectricOptions

Deterministic seed, branching, and glow shared by electrical texture recipes.

interface ElectricOptions

Related API: ElectricOptions.

Properties and methods

seed (optional)

readonly seed?: number | undefined

Seed used for deterministic sampling or simulation initialization. See ElectricOptions .

View source — packages/core/src/features/textures/lib/electric-shared.ts:38

branching (optional)

readonly branching?: number | undefined

0..1, controls the number of secondary branches.

View source — packages/core/src/features/textures/lib/electric-shared.ts:40

glow (optional)

readonly glow?: number | undefined

0..2, scales the soft halo without widening the white core.

View source — packages/core/src/features/textures/lib/electric-shared.ts:42

ElectricControl

Pause or reseed/reset commands shared by electrical textures.

type ElectricControl = | {
      /** The literal "pause" identifying this variant. See {@link ElectricControl}. */
      readonly type: "pause";
      /** Whether simulation or playback advancement is suspended. See {@link ElectricControl}. */
      readonly paused: boolean;
    }
  | {
      /** The literal "reset" identifying this variant. See {@link ElectricControl}. */
      readonly type: "reset";
      /**
       * Seed used for deterministic sampling or simulation initialization. See
       * {@link ElectricControl}.
       */
      readonly seed?: number;
    }

Related API: ElectricControl.

Properties and methods

type

readonly type: "pause" | "reset"

The literal “pause” identifying this variant. See ElectricControl. The literal “reset” identifying this variant. See ElectricControl.

View source — packages/core/src/features/textures/lib/electric-shared.ts:53

ElectricSource

A weighted attachment site in normalized texture coordinates.

interface ElectricSource

Related API: ElectricSource.

Properties and methods

readonly id: string

Stable identifier of this resource or connection. See ElectricSource.

View source — packages/core/src/features/textures/lib/electric-sources.ts:13

point

readonly point: ElectricPoint

Related API: ElectricPoint.

A point in the operation’s coordinate system. See ElectricPoint.

View source — packages/core/src/features/textures/lib/electric-sources.ts:15

weight

readonly weight: number

Relative sampling weight or source intensity. See ElectricSource.

View source — packages/core/src/features/textures/lib/electric-sources.ts:17

ElectricSourceMessage

Upserts, removes, or replaces the named source electrodes of an electrical texture.

Full type declaration

type ElectricSourceMessage = | {
      /** The literal "upsert-source" identifying this variant. See {@link ElectricSourceMessage}. */
      readonly type: "upsert-source";
      /** Named electrode to insert or replace. See {@link ElectricSource}. */
      readonly source: ElectricSource;
    }
  | {
      /** The literal "remove-source" identifying this variant. See {@link ElectricSourceMessage}. */
      readonly type: "remove-source";
      /** Stable identifier of this resource or connection. See {@link ElectricSourceMessage}. */
      readonly id: string;
    }
  | {
      /** The literal "set-sources" identifying this variant. See {@link ElectricSourceMessage}. */
      readonly type: "set-sources";
      /** Named electrical source electrodes. See {@link ElectricSource}. */
      readonly sources: readonly ElectricSource[];
    }

Related API: ElectricSourceMessage, ElectricSource.

Properties and methods

type

readonly type: "remove-source" | "set-sources" | "upsert-source"

View source — packages/core/src/features/textures/lib/electric-sources.ts:28

Implementation guidance for agents

Read the Textures and reaction-diffusion companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Connect two electric points: Render a lightning recipe and reset its deterministic seed on click. Plain source
Add a weighted filament source: Attach electric filaments to typed source sites and add one on click. Plain source

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 2dccb19. ALPHA — NOT FOR PRODUCTION USE.

Electric textures

ElectricControl

ElectricOptions

ElectricPoint

ElectricSource

ElectricSourceMessage

lightning

LightningMessage

LightningOptions

tendrils

TendrilsMessage

TendrilsOptions

API details from source

tendrils

Parameters

Returns

See also

TendrilsOptions

See also

Properties and methods

TendrilsMessage

See also

Properties and methods

lightning

Parameters

Returns

See also

LightningOptions

See also

Properties and methods

LightningMessage

See also

Properties and methods

ElectricPoint

See also

Properties and methods

ElectricOptions

See also

Properties and methods

ElectricControl

See also

Properties and methods

ElectricSource

See also

Properties and methods

ElectricSourceMessage

See also

Properties and methods

Implementation guidance for agents

Complete minimal examples

Documentation version