telperion 0.0.1 → 0.1.1

package/dist/browser/core.d.ts

@@ -0,0 +1,195 @@
+import type { LeafReference } from "./leaf";
+import { type SpecimenHandle, type SpecimenSnapshot } from "./specimen";
+import { type Family } from "./presets.generated";
+export type { Family } from "./presets.generated";
+export interface TreePreset extends Family {
+    id: string;
+    name: string;
+    note: string;
+}
+/** Explicit identity lookup; unknown identities never fall back to Ordinary. */
+export declare function presetById(id: string): TreePreset;
+/** Plain parameter baseline, usable directly at the native request boundary. */
+export declare const ORDINARY: Family;
+export declare const OREGON_WHITE_OAK: TreePreset;
+export declare const NORWAY_SPRUCE: TreePreset;
+export declare const SILVER_BIRCH: TreePreset;
+export declare const TELPERION: TreePreset;
+export declare const LAURELIN: TreePreset;
+export declare const TWO_TREES: TreePreset[];
+export declare const PRESETS: TreePreset[];
+export interface Outputs {
+    surface?: boolean;
+    foliage?: boolean;
+    structure?: boolean;
+    /** Wood and foliage occupancy from the solved tree and the leaf plan: no
+     * leaf is placed for a family the plan describes. A family without a plan
+     * places and culls its leaves for the field; no render buffers transfer
+     * unless surface/foliage are requested separately. `true` names limbs at
+     * the family's `clumpSystemOrder`; `{ limbOrder }` at that lateral order,
+     * a higher one parting the crown into more and smaller systems. */
+    field?: boolean | {
+        limbOrder: number;
+    };
+}
+export interface Bounds {
+    min: [number, number, number];
+    max: [number, number, number];
+}
+export interface Timings {
+    growthMs: number;
+    surfaceMs: number;
+    planMs: number;
+    foliageMs: number;
+    fieldMs: number;
+    coreMs: number;
+    transferMs: number;
+    buildMs: number;
+}
+/** Which stages a build ran. `foliage` is the placement and the cull together;
+ * `contacts` the wood's contact surface under placement; `plan` the leaf plan
+ * a field request read. `fieldSource` names the field's foliage path. */
+export interface Stages {
+    surface: boolean;
+    foliage: boolean;
+    placement: boolean;
+    cull: boolean;
+    contacts: boolean;
+    plan: boolean;
+    field: boolean;
+    fieldSource: "plan" | "placed" | null;
+}
+/** Half-open prototype ranges exclude connectors; indices are scalar offsets. */
+export interface FoliageAnatomy {
+    unit: "leaf" | "needle";
+    vertices: [number, number];
+    indices: [number, number];
+    sections: [number, number][];
+}
+export interface Diagnostics {
+    biologicalUnits: number | null;
+    foliageAnatomy: FoliageAnatomy | null;
+    nodes: number;
+    crossover: number;
+    shed: number;
+    capped: boolean;
+    levelCapped: boolean;
+    attractionCapped: boolean;
+    complete: boolean;
+    handoffs: number;
+    generationCounts: number[];
+    levelCappedHandoffs: number;
+    twigs: number;
+    leavesPlaced: number;
+    instances: number;
+    /** Stations the leaf plan counts before any cull; zero without a plan. */
+    leavesPlanned: number;
+    surfaceBounds: Bounds | null;
+    foliageBounds: Bounds | null;
+    /** The box every packed leaf position is quantised against. */
+    foliageReference: LeafReference | null;
+    fieldBounds: Bounds | null;
+    fieldBytes: number;
+    revision: number;
+    timings: Timings;
+    stages: Stages;
+}
+/** One batch query's answers, one entry per cell. `flags` bits: wood=1,
+ * foliage=2. `woodRadius` is the thickest wood sweep reaching the cell in
+ * metres, zero without wood. `leaves` estimates the stations in the cell
+ * before the crown cull (the retained leaves overlapping it on the placed
+ * path). `limbs` is the owning limb system, UINT32_MAX where no foliage
+ * reaches. */
+export interface FieldQuery {
+    flags: Uint8Array;
+    woodRadius: Float32Array;
+    leaves: Float32Array;
+    limbs: Uint32Array;
+}
+/** Owned canonical f64 CPU BVH data for generation experiments; survives release,
+ * rebuild and disposal. Mutating these arrays cannot alter the native field.
+ * Bounds: six f64 min/max xyz per node then item. Topology: four u32 per
+ * node [start,end,left,right], then primitive IDs; UINT32_MAX children = leaf. */
+export interface FieldIndexSnapshot {
+    bounds: Float64Array;
+    topology: Uint32Array;
+    nodeCount: number;
+}
+export interface FieldSnapshot {
+    schema: 2;
+    revision: number;
+    bounds: Bounds | null;
+    /** Eight f64: a xyz, b xyz, proximal and distal radius. */
+    wood: Float64Array;
+    woodIndex: FieldIndexSnapshot;
+    /** Placed-leaf boxes; empty on a planned field. */
+    leaves: FieldIndexSnapshot;
+    /** The leaf plan's sweeps: seven f64 (a xyz, b xyz, reach) and two u32
+     * (station count, limb system) a sweep, with their index. Empty on a
+     * placed field. */
+    plan: {
+        segments: Float64Array;
+        stations: Uint32Array;
+        index: FieldIndexSnapshot;
+    };
+    timings: {
+        extractionMs: number;
+        copyMs: number;
+        totalMs: number;
+    };
+}
+export interface TreeOutput {
+    surface?: {
+        positions: Float32Array;
+        normals: Float32Array;
+        indices: Uint32Array;
+        bounds: Bounds | null;
+    };
+    /** Three u32 words a leaf, decoded against `reference` by `./leaf`. The
+     * sixteen-float form is never built here: twelve bytes are the storage. */
+    foliage?: {
+        positions: Float32Array;
+        indices: Uint32Array;
+        leaves: Uint32Array;
+        reference: LeafReference | null;
+        anatomy: FoliageAnatomy | null;
+        bounds: Bounds | null;
+    };
+    /** Six f64 values per node: xyz, distal radius, proximal radius, base radius.
+     * Three u32 values per node: parent (UINT32_MAX for root), branch, kind (0/1/2). */
+    structure?: {
+        values: Float64Array;
+        topology: Uint32Array;
+    };
+    /** Query packed x,y,z,halfExtent cells. Invalid after this engine's next
+     * build or release; copied results remain owned. */
+    field?: {
+        query(cells: Float64Array): FieldQuery;
+        snapshot(): FieldSnapshot;
+    };
+    diagnostics: Diagnostics;
+}
+export declare class TreeEngine {
+    private exports;
+    private get e();
+    get disposed(): boolean;
+    private constructor();
+    /** Drop the instance, allowing its linear memory to be reclaimed by the host. */
+    dispose(): void;
+    static create(source?: BufferSource | Response): Promise<TreeEngine>;
+    private metadata;
+    private check;
+    /** Releases native outputs and invalidates fields; JS copies remain usable.
+     * Wasm linear memory retains its high-water capacity for allocator reuse. */
+    release(): void;
+    private specimens;
+    buildSpecimen(family: Family | string, historyCap?: number): SpecimenHandle;
+    importSpecimen(snapshot: SpecimenSnapshot): SpecimenHandle;
+    get memoryBytes(): number;
+    build(family: Family | string, outputs: Outputs): TreeOutput;
+    private snapshot;
+    private query;
+}
+/** Harness convenience; independent consumers can create their own TreeEngine. */
+export declare function initializeTreeCore(source?: BufferSource | Response): Promise<TreeEngine>;
+export declare function treeCore(): TreeEngine;

package/dist/browser/leaf.d.ts

@@ -0,0 +1,39 @@
+/** One leaf in twelve bytes, read exactly as the core packed it.
+ *
+ * The three words are the storage on both sides of the wire, so this is the
+ * only place in the browser source that knows the bit layout: a second copy
+ * would be a reader free to drift from the writer. The Rust encoder of record
+ * is `telperion-core`'s `foliage::packed`, and the shader that draws these
+ * words is `leaf.wgsl`; all three decode one leaf one way.
+ *
+ * Word 0 is the rotation as a smallest-three quaternion - the index of the
+ * dropped largest component in the top two bits, the other three below it, ten
+ * bits each, over plus or minus one over root two. Word 1 is x and y as
+ * unsigned normals over the reference box, word 2 is z in its low half and the
+ * uniform scale as a half float in its high half. */
+/** Words one stored leaf occupies. */
+export declare const LEAF_WORDS = 3;
+export type Vector = [number, number, number];
+/** The three words of one leaf, in storage order: rotation, xy, z and scale. */
+export type LeafWords = readonly [number, number, number];
+/** The box leaf positions are quantised against. It comes from the family's
+ * parameters, not from the tree that grew, so one box decodes a species at
+ * every age; the build metadata and a specimen read both carry it. */
+export interface LeafReference {
+    min: Vector;
+    extent: Vector;
+}
+/** The words of one leaf in a packed buffer, by instance index. */
+export declare function leafWords(leaves: Uint32Array, index: number): LeafWords;
+/** Where a leaf stands. The crown's bounds and any spatial pass read nothing
+ * else, so neither pays for a rotation it never uses. */
+export declare function leafPosition(words: LeafWords, reference: LeafReference): Vector;
+/** The uniform scale a leaf carries, out of the high half of word 2. */
+export declare function leafScale(words: LeafWords): number;
+/** The rotation word 0 carries, as the three columns of its matrix: side, the
+ * leaf's own axis, face. */
+export declare function leafRotation(words: LeafWords): [Vector, Vector, Vector];
+/** The whole transform three words stand for, column-major, as the sixteen
+ * floats the core used to write: the rotation's columns at the stored scale,
+ * and the stored position in column three. */
+export declare function leafTransform(words: LeafWords, reference: LeafReference): Float32Array;

package/dist/browser/presets.generated.d.ts

@@ -0,0 +1,278 @@
+export interface Family {
+    age: number;
+    canopy: {
+        acanthophyllLength: number;
+        acanthophyllPitch: number;
+        acanthophylls: number;
+        clump: number;
+        clumpNeighbours: number;
+        clumpSpan: number;
+        clumpSystemOrder: number;
+        divergence: number;
+        forwardLean: number;
+        leafBaseLength: number;
+        leafBasePitch: number;
+        leafBaseRadius: number;
+        leafBaseWeathering: number;
+        leafBases: number;
+        leafletCount: number;
+        leafletPitch: number;
+        leanRise: number;
+        limbClumping: number;
+        maxInstances: number;
+        outward: number;
+        rachisArch: number;
+        rachisLength: number;
+        rosetteDepth: number;
+        rosetteDivergence: number;
+        rosetteFronds: number;
+        rosettePitch: number;
+        rosettePitchSpread: number;
+        scatter: number;
+        shootRadius: number;
+        shortShootLeaves: number;
+        shortShootLength: number;
+        shortShootRadius: number;
+        shortShootSpacing: number;
+        shortShootSpread: number;
+        size: number;
+        sizeVariation: number;
+        spacing: number;
+        surfaceContact: number;
+        terminalLeaflet: number;
+        upward: number;
+    };
+    element: {
+        axialSegments: number;
+        baseFullness: number;
+        card: boolean;
+        connectorLength: number;
+        crossSegments: number;
+        cup: number;
+        curl: number;
+        length: number;
+        lobeCount: number;
+        lobeDepth: number;
+        sectionRoundness: number;
+        tipSharpness: number;
+        widestAt: number;
+        width: number;
+    };
+    growth: {
+        apicalControlLoss: number;
+        leafLifetime: number;
+        rate: number;
+        resizeTolerance: number;
+        shape: number;
+        sheddingTolerance: number;
+        workBudget: number;
+    };
+    material: {
+        barkBlue: number;
+        barkGrainScale: number;
+        barkGrainStrength: number;
+        barkGreen: number;
+        barkMottleScale: number;
+        barkMottleStrength: number;
+        barkRed: number;
+        barkReflectance: number;
+        barkRoughness: number;
+        bladeGrainScale: number;
+        bladeGrainStrength: number;
+        bladeMottleScale: number;
+        bladeMottleStrength: number;
+        brightnessRangeHigh: number;
+        brightnessRangeLow: number;
+        canopyNormal: number;
+        cavityStrength: number;
+        crestBlue: number;
+        crestGreen: number;
+        crestRed: number;
+        crestStrength: number;
+        crownShade: number;
+        cuticleGloss: number;
+        depthStrength: number;
+        diffuseTransmission: number;
+        directionalOcclusion: number;
+        fissureBlue: number;
+        fissureGreen: number;
+        fissureRed: number;
+        fissureStrength: number;
+        furrowStrength: number;
+        hueRangeHigh: number;
+        hueRangeLow: number;
+        interiorDarkening: number;
+        leafBackBlue: number;
+        leafBackGreen: number;
+        leafBackRed: number;
+        leafFrontBlue: number;
+        leafFrontGreen: number;
+        leafFrontRed: number;
+        leafReflectance: number;
+        leafSheen: number;
+        lenticelDensity: number;
+        lenticelLength: number;
+        lenticelStrength: number;
+        lenticelTint: number;
+        lichenBlue: number;
+        lichenCoverage: number;
+        lichenGreen: number;
+        lichenRed: number;
+        lichenScale: number;
+        lichenStrength: number;
+        lightWrap: number;
+        lobeShade: number;
+        marginBlue: number;
+        marginGreen: number;
+        marginRed: number;
+        marginWidth: number;
+        orientationBlue: number;
+        orientationGreen: number;
+        orientationRed: number;
+        orientationStrength: number;
+        peelBlue: number;
+        peelCurl: number;
+        peelGreen: number;
+        peelRed: number;
+        plateCellScale: number;
+        plateDome: number;
+        plateEdgeLift: number;
+        plateEdgeShape: number;
+        plateElongation: number;
+        plateFurrowWidth: number;
+        plateIdentity: number;
+        plateScale: number;
+        ridgeScale: number;
+        roughnessDetail: number;
+        shootBlue: number;
+        shootGreen: number;
+        shootRadius: number;
+        shootRed: number;
+        skyOcclusionStrength: number;
+        thickness: number;
+        transmissionBlue: number;
+        transmissionGreen: number;
+        transmissionRed: number;
+        transmissionStrength: number;
+        veinContrast: number;
+        veinScale: number;
+        weatheringBlue: number;
+        weatheringGreen: number;
+        weatheringRed: number;
+        weatheringStrength: number;
+    };
+    radii: {
+        forkExponent: number;
+        lengthTaper: number;
+        maxTaperExponent: number;
+        trunkRadius: number;
+    };
+    shellDepth: number;
+    skeleton: {
+        attractors: number;
+        bias: {
+            gravitropism: number;
+            lean: number;
+            supernatural: {
+                enabled: boolean;
+                maxWritheMagnitude: number;
+                spiralRate: number;
+                writheAmplitude: number;
+                writheWavelength: number;
+            };
+        };
+        envelope: {
+            crownBase: number;
+            fullness: number;
+            height: number;
+            irregularity: number;
+            lobeScale: number;
+            shoulder: number;
+            spread: number;
+        };
+        growth: {
+            influenceRadius?: number;
+            killDistance?: number;
+            maxNodes?: number;
+            maxTurnPerStep: number;
+            stepDistance?: number;
+            trunkHeight?: number;
+        };
+        habit: {
+            apicalDominance: number;
+            attractorWeight: number;
+            crookedness: number;
+            lateralLengthRatio: number;
+            lateralOrders: number;
+            lateralPitch: number;
+            lateralSpacing: number;
+            lateralsPerStation: number;
+            leaderInternode: number;
+            pitchVariation: number;
+            reachProbeSteps: number;
+            risePrimary: number;
+            riseSecondary: number;
+            sheddingThreshold: number;
+            stemDivergence: number;
+            stemForkHeight: number;
+            stemLean: number;
+            stemLeanSpread: number;
+            stems: number;
+            twigTipTaper: number;
+            whorlStrength: number;
+        };
+        samplingAttemptsPerAttractor: number;
+        seed: number;
+        step: number;
+        twigs: {
+            angle: number;
+            angleVariation: number;
+            curtainClearance: number;
+            curtainDrop: number;
+            curtainSeparation: number;
+            curtainStepClearance: number;
+            divergence: number;
+            generations: number;
+            hang: number;
+            internodeFactor: number;
+            laterals: number;
+            lengthRatio: number;
+            limbRadius: number;
+            maxDroop: number;
+            maxInternodes: number;
+            pendulousLength: number;
+            pendulousRadius: number;
+            pendulousVariation: number;
+            ratioPower: number;
+            reach: number;
+            sag: number;
+            twig: {
+                bearingDiameter: number;
+                diameter: number;
+                internodeLength: number;
+                length: number;
+                stationsPerInternode: number;
+            };
+            vigourVariation: number;
+        };
+    };
+    surface: {
+        flareDepth: number;
+        flareFalloff: number;
+        flareRadius: number;
+        forkSocket: number;
+        forkSwell: number;
+        lobeDepth: number;
+        lobes: number;
+        radialSegments: number;
+        socketContainment: number;
+        twistRate: number;
+    };
+}
+export declare const CATALOGUE: {
+    abiId: number;
+    id: string;
+    name: string;
+    note: string;
+    family: Family;
+}[];

package/dist/browser/render.d.ts

@@ -0,0 +1,165 @@
+/** Metres, Y up, right-handed - the renderer's own frame. */
+export type Point = readonly [number, number, number];
+export interface Submitted {
+    woodVertices: number;
+    woodTriangles: number;
+    foliageInstances: number;
+    bounds: {
+        min: Point;
+        max: Point;
+    };
+}
+/** Host wall-clock milliseconds (`Ms`) and selected allocation capacities (`Bytes`).
+ * Timings can nest/overlap; memory snapshots share allocations and are not additive.
+ * These omit some transient scratch, allocator-retained Wasm memory, upload staging,
+ * driver allocations and deferred destruction; they are not whole-process peaks.
+ * Zero/default fields can mean an unused stage. */
+export interface GenerationStages {
+    positionPrepareMs: number;
+    positionUploadMs: number;
+    /** Admission wait remaining after overlapping CPU station work. */
+    positionWaitMs: number;
+    positionCpuBytes: number;
+    positionGpuPeakBytes: number;
+    positionRetainedMetadataBytes: number;
+    /** Unstable diagnostic text; do not branch on its wording. */
+    positionFallback: string | null;
+    gpuPositions: boolean;
+    skeletonMs: number;
+    descriptorsMs: number;
+    uploadDispatchMs: number;
+    placementWaitMs: number;
+    compactMs: number;
+    massMs: number;
+    readbackMs: number;
+    woodMs: number;
+    woodPrepareMs: number;
+    woodUploadDispatchMs: number;
+    woodWaitMs: number;
+    woodPreparedCpuBytes: number;
+    woodMetadataCpuBytes: number;
+    woodGpuPeakBytes: number;
+    woodBackend: "Cpu" | "Gpu" | "CpuFallback" | null;
+    /** Unstable diagnostic text; do not branch on its wording. */
+    woodFallback: string | null;
+    /** Preparation only; excludes adoption, drawing and completed-frame fencing. */
+    totalMs: number;
+    baseCpuBytes: number;
+    woodCpuBytes: number;
+    descriptorCpuBytes: number;
+    sharedContactCpuBytes: number;
+    sharedPrepareCpuBytes: number;
+    sharedMetadataCpuBytes: number;
+    gpuComputePeakBytes: number;
+    retainedGpuBytes: number;
+}
+/** A tree adopted by the renderer; this promise does not fence a completed frame. */
+export interface GpuSubmitted extends Submitted {
+    backend: "Gpu" | "CpuFallback";
+    stages: GenerationStages;
+    /** Allocated live-tree GPU buffer bytes before adoption; excludes textures/pipelines. */
+    previousTreeGpuBytes: number;
+    /** Allocated live-tree GPU buffer bytes after adoption, with the same exclusions. */
+    treeGpuBytes: number;
+}
+export interface FrameStats {
+    drawCalls: number;
+    triangles: number;
+    instances: number;
+}
+export interface Pose {
+    position: Point;
+    target: Point;
+}
+/** The timing session's record, as the Rust report writes it, field for
+ *  field. The GPU percentiles exist only on a valid verdict, so nothing
+ *  in an invalid record can be read as a number that passed. The wall
+ *  clock is the page's own and not the GPU's, so an orbit reports it even
+ *  where there was no GPU clock to read. */
+export interface TimingReport {
+    adapter: string;
+    driver: string;
+    backend: string;
+    conditioning: number;
+    warmup: number;
+    measured: number;
+    samples: number;
+    multisample: number;
+    caster_triangles: number;
+    caster_instances: number;
+    verdict: "valid" | "unavailable" | "disjoint" | "contended";
+    reason?: string;
+    p50_ms?: number;
+    p95_ms?: number;
+    /** The selection compute pass that decides what the vegetation pass draws. */
+    selection_p50_ms?: number;
+    selection_p95_ms?: number;
+    shadow_p50_ms?: number;
+    shadow_p95_ms?: number;
+    /** Three passes added frame by frame and then ranked: a frame's own cost. */
+    total_p50_ms?: number;
+    total_p95_ms?: number;
+    /** What each level drew, coarsest first, and last the bucket of leaves
+     *  no level drew - which approximated nothing, so it has no deviation.
+     *  Read back only where a session can read the counters. */
+    levels?: {
+        deviation_m: number | null;
+        instances_p50: number;
+    }[];
+    /** Frame to frame on the page's own animation clock, over an orbit. */
+    wall_frames?: number;
+    wall_p50_ms?: number;
+    wall_p95_ms?: number;
+    wall_max_ms?: number;
+}
+export type View = "whole" | "bare" | "leaf" | "clay";
+/** The sun, the sky and the ground, as the renderer states them. The row is
+ *  defined in Rust and read back out of the renderer, so nothing on this side
+ *  keeps a second copy of its fields or of their default values: a field the
+ *  row grows appears in the panel with no line here. */
+export type SceneRow = Record<string, number>;
+/** Devices created minus devices disposed, on the window, for the soak
+ *  test to read. React's development double-mount builds one renderer
+ *  and disposes it before the live one, so "one canvas, one device" is
+ *  a claim only a counter that survives both mounts can check. */
+declare global {
+    interface Window {
+        telperionLiveDevices?: number;
+    }
+}
+/** One canvas drawn by the Rust renderer, sized to the display and
+ *  disposed with the page element it belongs to. */
+export interface GrowthSubmitted extends Submitted {
+    age: number;
+    frontier: number;
+}
+export interface Renderer {
+    setTree(family: string): Submitted;
+    /** Experimental GPU foliage; unsupported inputs report CpuFallback. */
+    setTreeGpu(family: string): Promise<GpuSubmitted>;
+    buildSpecimen(family: string, age: number): GrowthSubmitted;
+    seekSpecimen(age: number): GrowthSubmitted;
+    setView(view: View): void;
+    /** The sun, sky and ground the next frame is drawn under. */
+    scene(): SceneRow;
+    /** Stands the sun somewhere else, on top of the row already set. Throws the
+     *  renderer's own words for a value it will not have, and the sky the
+     *  renderer is drawing under stays exactly where it was. */
+    setScene(row: SceneRow): void;
+    /** Puts the camera at the judging pose for what is on the canvas, and
+     *  reports where that left it. Null before a tree has been submitted. */
+    hero(): Pose | null;
+    setCamera(pose: Pose): void;
+    frame(): void;
+    stats(): FrameStats;
+    timing(): Promise<TimingReport>;
+    /** The same session while the camera makes one full turn about the pose
+     *  it stands at, ending with ten seconds of frames drawn the way this
+     *  loop draws them - which is where the record's wall numbers come from. */
+    orbit(): Promise<TimingReport>;
+    dispose(): void;
+}
+/** Loads the module once per page and puts a renderer on this canvas.
+ *  Rejects with the renderer's own words when there is no WebGPU, only a
+ *  software adapter, or the device is refused. */
+export declare function createRenderer(canvas: HTMLCanvasElement): Promise<Renderer>;

package/dist/browser/specimen-wire.d.ts

@@ -0,0 +1,22 @@
+import type { ChangeRecord, NodeIdentity, PlacementIdentity } from './specimen';
+/** The fixed little-endian record ABI, not a view into retained wasm memory. */
+export declare class SpecimenWire {
+    private offset;
+    private view;
+    constructor(bytes: Uint8Array);
+    private u8;
+    private u32;
+    private u64;
+    private f64;
+    private vector;
+    private node;
+    private identity;
+    private placement;
+    private run;
+    identities(): {
+        nodes: NodeIdentity[];
+        placements: PlacementIdentity[];
+        shed: NodeIdentity[];
+    };
+    changes(): ChangeRecord;
+}