@layoutit/polycss 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -1,99 +1,106 @@
-import { P as PolySceneHandle, a as PolyMeshHandle } from './PolySelectElement-Tvsmhx2m.cjs';
-export { b as PolyCameraOptions, c as PolyMapControlsElement, d as PolyMeshElement, e as PolyMeshTransform, f as PolyOrbitControlsElement, g as PolyOrthographicCameraElement, h as PolyOrthographicCameraHandle, i as PolyOrthographicCameraOptions, j as PolyPerspectiveCameraElement, k as PolyPerspectiveCameraHandle, l as PolyPerspectiveCameraOptions, m as PolyPolygonElement, n as PolyRenderStrategiesOption, o as PolyRenderStrategy, p as PolySceneElement, q as PolySceneOptions, r as PolySelectElement, s as PolyTransformControlsElement, T as TextureQuality, t as createPolyOrthographicCamera, u as createPolyPerspectiveCamera, v as createPolyScene } from './PolySelectElement-Tvsmhx2m.cjs';
-import { Vec3 } from '@layoutit/polycss-core';
+import { P as PolySceneOptions, a as PolySceneHandle, b as PolyControlsHandle, c as PolyControlsBaseOptions, d as PolyControlsEvent, e as PolyControlsListener, f as PolyMeshHandle } from './PolyShapeElements-BNHvErQF.cjs';
+export { g as PolyBoxElement, h as PolyCameraElement, i as PolyCameraOptions, j as PolyConeElement, k as PolyControlsAnimateOptions, l as PolyControlsCamera, m as PolyControlsChangeEvent, n as PolyControlsInteractionEvent, o as PolyCylinderElement, p as PolyDodecahedronElement, q as PolyFirstPersonControlsElement, r as PolyIcosahedronElement, s as PolyIframeElement, t as PolyMapControlsElement, u as PolyMeshElement, v as PolyMeshTransform, w as PolyOctahedronElement, x as PolyOrbitControlsElement, y as PolyOrbitControlsHandle, z as PolyOrbitControlsOptions, A as PolyOrthographicCameraElement, B as PolyOrthographicCameraHandle, C as PolyOrthographicCameraOptions, D as PolyPerspectiveCameraElement, E as PolyPerspectiveCameraHandle, F as PolyPerspectiveCameraOptions, G as PolyPlaneElement, H as PolyPolygonElement, I as PolyRingElement, J as PolySceneElement, K as PolySelectElement, L as PolySphereElement, M as PolyTetrahedronElement, N as PolyTorusElement, O as PolyTransformControlsElement, Q as createPolyCamera, R as createPolyOrbitControls, S as createPolyOrthographicCamera, T as createPolyPerspectiveCamera } from './PolyShapeElements-BNHvErQF.cjs';
+import * as _layoutit_polycss_core from '@layoutit/polycss-core';
+import { PolyDirectionalLight, PolyAmbientLight, PolyTextureLightingMode, TextureAtlasPlan, TextureQuality, PackedAtlas, PackedPage, TextureAtlasPage, PolyRenderStrategy, SolidPaintDefaults, Polygon, SolidTriangleFrame, Vec3, BoxPolygonsOptions, ParseResult, ConePolygonsOptions, CylinderPolygonsOptions, DodecahedronPolygonsOptions, IcosahedronPolygonsOptions, OctahedronPolygonsOptions, PlanePolygonsOptions, RingPolygonsOptions, SpherePolygonsOptions, TetrahedronPolygonsOptions, TorusPolygonsOptions } from '@layoutit/polycss-core';
 export * from '@layoutit/polycss-core';
+export { ComputeTextureAtlasPlanOptions, PackedAtlas, PackedPage, PackedTextureAtlasEntry, PolyRenderStrategiesOption, PolyRenderStrategy, ParseResult as PolyShapeResult, SolidPaintDefaults, SolidTriangleFrame, TextureAtlasPage, TextureAtlasPlan, TextureQuality, buildTextureEdgeRepairSets, computeTextureAtlasPlanPublic, cssBorderShapeForPlan, formatBorderShapeEntryMatrix, formatCssLengthPx, formatMatrix3d, formatSolidQuadEntryMatrix, isFullRectSolid, isProjectiveQuadPlan, isSolidTrianglePlan } from '@layoutit/polycss-core';
 
-/**
- * Shared types, constants, and utilities for orbit/map controls factories.
- * Not part of the public API surface — use createPolyOrbitControls or
- * createPolyMapControls.
- */
-
-interface PolyControlsAnimateOptions {
-    /**
-     * Rotation rate in degrees per 60 Hz-equivalent frame. The tick is
-     * dt-clamped so 0.3 deg/frame ≈ 18 deg/sec on every refresh rate.
-     * Default: 0.3.
-     */
-    speed?: number;
-    /** Rotation axis. Default: "y" (yaw, rotates around vertical world Z). */
-    axis?: "x" | "y";
-    /** Halt the loop while a pointer drag is in progress. Default: true. */
-    pauseOnInteraction?: boolean;
-}
-interface PolyControlsBaseOptions {
-    /** Pointer-drag. Default: true. */
-    drag?: boolean;
-    /** Wheel / pinch zoom. Default: true. */
-    wheel?: boolean;
+interface RenderTextureAtlasOptions {
+    doc?: Document;
+    tileSize?: number;
+    layerElevation?: number;
+    directionalLight?: PolyDirectionalLight;
+    ambientLight?: PolyAmbientLight;
+    textureLighting?: PolyTextureLightingMode;
     /**
-     * When `true`, wheel events change `distance` (camera pull-back in CSS px)
-     * instead of `zoom`. Mirrors Three.js OrbitControls dolly behaviour.
-     * Default: false (zoom mode).
+     * Atlas bitmap budget and CSS sprite size. Numeric values are clamped to
+     * 0.1..1 and keep the 64px sprite. Omitted / `"auto"` picks a raster scale
+     * from packed atlas area, caps oversized runtime bitmaps by side length and
+     * decoded-memory budget, and uses a 128px sprite on desktop-class documents
+     * or a 64px sprite on mobile-class documents.
      */
-    dolly?: boolean;
+    textureQuality?: _layoutit_polycss_core.TextureQuality;
+    solidPaintDefaults?: _layoutit_polycss_core.SolidPaintDefaults;
+    strategies?: _layoutit_polycss_core.PolyRenderStrategiesOption;
     /**
-     * Drag-direction inversion. `false` = natural, `true` = invert (×-1),
-     * a number multiplies sensitivity (negative inverts). Default: false.
+     * Indices of polygons that the directional light cannot reach (precomputed
+     * by createPolyScene via {@link computeLightVisibility}). Atlas + solid
+     * planning forces directScale to 0 for these polys so they render with
+     * ambient-only color, matching what a shadow-map pass would output.
      */
-    invert?: boolean | number;
-    /** Minimum CSS zoom. Default: 0.1. */
-    minZoom?: number;
-    /** Maximum CSS zoom. Default: 10. */
-    maxZoom?: number;
-    /** Minimum dolly distance in CSS pixels. Default: 0. Only used when `dolly: true`. */
-    minDistance?: number;
-    /** Maximum dolly distance in CSS pixels. Default: Infinity. Only used when `dolly: true`. */
-    maxDistance?: number;
-    /** Auto-rotate. Pass false (or omit) to disable. */
-    animate?: false | PolyControlsAnimateOptions;
+    lightOccludedPolyIndices?: ReadonlySet<number>;
 }
-interface PolyControlsCamera {
-    rotX: number;
-    rotY: number;
-    zoom: number;
-    target: Vec3;
-    distance: number;
+interface RenderedPoly {
+    polygonIndex: number;
+    element: HTMLElement;
+    kind?: "atlas" | "solid" | "border" | "corner" | "triangle";
+    plan?: _layoutit_polycss_core.TextureAtlasPlan;
+    dispose(): void;
 }
-interface PolyControlsChangeEvent {
-    type: "change";
-    camera: PolyControlsCamera;
+interface RenderTextureAtlasResult {
+    rendered: RenderedPoly[];
+    dispose(): void;
+    /**
+     * Resolves once every textured `<s>` leaf has its `background-image`
+     * applied (i.e. the atlas canvas → Blob → URL chain has completed and
+     * the apply-bg pass has run). For meshes with no textured leaves this
+     * resolves immediately. Callers doing stale-while-revalidate swaps
+     * await this before disposing the previous render — without it, the
+     * fresh leaves mount with empty backgrounds and the prior frame's
+     * bitmaps would be needed underneath to avoid a transparent flash.
+     */
+    pagesReady?: Promise<void>;
 }
-interface PolyControlsInteractionEvent {
-    type: "start" | "end";
-    camera: PolyControlsCamera;
-}
-type PolyControlsEvent = PolyControlsChangeEvent | PolyControlsInteractionEvent;
-type PolyControlsListener<E extends PolyControlsEvent = PolyControlsEvent> = (event: E) => void;
-interface PolyControlsHandle {
-    update(partial: PolyControlsBaseOptions): void;
-    resume(): void;
-    pause(): void;
-    destroy(): void;
-    addEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
-        type: T;
-    }>>): void;
-    removeEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
-        type: T;
-    }>>): void;
-    hasEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
-        type: T;
-    }>>): boolean;
+interface RenderTextureAtlasAsyncResult extends RenderTextureAtlasResult {
+    solidPaintDefaults: _layoutit_polycss_core.SolidPaintDefaults;
 }
 
+declare function packTextureAtlasPlansWithScale(plans: Array<TextureAtlasPlan | null>, textureQualityInput: TextureQuality | undefined, doc: Document | null | undefined): {
+    packed: PackedAtlas;
+    atlasScale: number;
+    atlasCanonicalSize: number;
+};
+
+declare function buildAtlasPages(pages: PackedPage[], textureLighting: PolyTextureLightingMode, doc: Document, atlasScale: number, isCancelled: () => boolean): Promise<TextureAtlasPage[]>;
+
 /**
- * createPolyOrbitControls — orbit-mode camera input for a PolyScene.
+ * Compute the dominant paint defaults from an already-computed array of plans.
  *
- * Left-drag rotates rotX / rotY around the target (orbit). Wheel zooms or
- * dollies. Mirrors Three.js OrbitControls semantics.
- *
- * For map/pan semantics (left-drag pans, right-drag orbits) use
- * `createPolyMapControls` instead.
+ * React and Vue compute plans first (to drive the atlas packing), then pass
+ * the plan array here so they don't need access to the raw polygon list.
+ * Requires access to a Document to check browser support for solid-triangle
+ * and border-shape strategies.
+ */
+declare function getSolidPaintDefaultsFromPlans(plans: Array<TextureAtlasPlan | null>, textureLighting: PolyTextureLightingMode, disabled?: ReadonlySet<PolyRenderStrategy>, doc?: Document | null): SolidPaintDefaults;
+/**
+ * Returns true when the browser supports the `border-shape` CSS property and
+ * the pointer/hover media queries indicate a fine-pointer device (desktop-class).
+ * Falls back to a globalThis-based check when no Document is available.
+ */
+declare function isBorderShapeSupported(doc?: Document | null): boolean;
+/**
+ * Returns true when the browser renders CSS border-trick triangles correctly.
+ * WebKit/Safari renders them incorrectly when transformed — this check gates
+ * the `<u>` strategy path.
+ */
+declare function isSolidTriangleSupported(doc?: Document | null): boolean;
+/**
+ * Filter a plan array to the subset that needs atlas packing, given the active
+ * render strategies and texture-lighting mode. Plans excluded from the atlas
+ * will be rendered via `<b>`, `<i>`, or `<u>` by the framework components.
  */
+declare function filterAtlasPlans(plans: Array<TextureAtlasPlan | null>, textureLighting: PolyTextureLightingMode, disabled: ReadonlySet<PolyRenderStrategy>, doc?: Document | null): Array<TextureAtlasPlan | null>;
+
+declare function getSolidPaintDefaults(polygons: Polygon[], options?: RenderTextureAtlasOptions): SolidPaintDefaults;
+declare function renderPolygonsWithTextureAtlas(polygons: Polygon[], options?: RenderTextureAtlasOptions): RenderTextureAtlasResult;
+declare function renderPolygonsWithTextureAtlasAsync(polygons: Polygon[], options?: RenderTextureAtlasOptions, shouldCancel?: () => boolean): Promise<RenderTextureAtlasAsyncResult>;
+declare function updateStableTriangleFrame(rendered: RenderedPoly[], polygons: Polygon[], frame: SolidTriangleFrame, options?: RenderTextureAtlasOptions): boolean;
+declare function updatePolygonsWithStableTopology(rendered: RenderedPoly[], polygons: Polygon[], options?: RenderTextureAtlasOptions): boolean;
+
+declare function renderPolygonsWithStableTriangles(polygons: Polygon[], options?: RenderTextureAtlasOptions): RenderTextureAtlasResult | null;
+declare function updatePolygonsWithStableTriangles(rendered: RenderedPoly[], polygons: Polygon[], options?: RenderTextureAtlasOptions): RenderTextureAtlasResult | null;
 
-type PolyOrbitControlsOptions = PolyControlsBaseOptions;
-type PolyOrbitControlsHandle = PolyControlsHandle;
-declare function createPolyOrbitControls(scene: PolySceneHandle, options?: PolyOrbitControlsOptions): PolyOrbitControlsHandle;
+declare function createPolyScene(host: HTMLElement, options: PolySceneOptions): PolySceneHandle;
 
 /**
  * createPolyMapControls — map/pan-mode camera input for a PolyScene.
@@ -191,7 +198,7 @@ interface PolyFirstPersonControlsHandle {
 declare function createPolyFirstPersonControls(scene: PolySceneHandle, options?: PolyFirstPersonControlsOptions): PolyFirstPersonControlsHandle;
 
 /**
- * createSelect — additive selection layer for vanilla polycss scenes.
+ * createSelect — additive selection layer for vanilla PolyCSS scenes.
  * Mirrors the React `<Select>` API: tracks one or more selected
  * meshes, fires `onChange` whenever the set changes, supports
  * single-click toggle (re-clicking the selected mesh deselects it),
@@ -295,6 +302,60 @@ interface PolyTransformControlsHandle {
 }
 declare function createTransformControls(scene: PolySceneHandle, options?: PolyTransformControlsOptions): PolyTransformControlsHandle;
 
+interface PolyRenderSurfaceLeafCounts {
+    quad: number;
+    clippedSolid: number;
+    atlas: number;
+    stableTriangle: number;
+}
+interface PolyRenderStats {
+    polygonCount: number;
+    mountedPolygonLeafCount: number;
+    shadowLeafCount: number;
+    surfaceLeafCounts: PolyRenderSurfaceLeafCounts;
+    bucketCount: number;
+}
+interface PolyRenderStatsOptions {
+    polygonCount?: number;
+    /**
+     * Optional subtree selector for diagnostics that only want model leaves and
+     * not helpers/floors/gizmos sharing the same scene root.
+     */
+    scopeSelector?: string;
+}
+declare function collectPolyRenderStats(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyRenderStats;
+
+type PolySceneSnapshotErrorCode = "INVALID_TARGET" | "SCENE_NOT_FOUND" | "ASSET_INLINE_FAILED";
+declare class PolySceneSnapshotError extends Error {
+    readonly code: PolySceneSnapshotErrorCode;
+    readonly url?: string;
+    constructor(code: PolySceneSnapshotErrorCode, message: string, url?: string);
+}
+/**
+ * Serialize the current rendered PolyCSS DOM into a standalone HTML document.
+ * The snapshot is intentionally static: it preserves the scene's current DOM,
+ * inlines CSS image assets, and emits no scripts or PolyCSS runtime imports.
+ */
+declare function exportPolySceneSnapshot(target: Element): Promise<string>;
+
+/**
+ * Primitive shape factories — thin wrappers over the polygon generators in
+ * @layoutit/polycss-core. Each returns a `ParseResult`-compatible object so
+ * it composes directly with `scene.add(createPolyBox({ size: 100 }))`.
+ */
+
+declare function createPolyBox(options?: BoxPolygonsOptions): ParseResult;
+declare function createPolyPlane(options: PlanePolygonsOptions): ParseResult;
+declare function createPolyRing(options: RingPolygonsOptions): ParseResult;
+declare function createPolyOctahedron(options: OctahedronPolygonsOptions): ParseResult;
+declare function createPolySphere(options?: SpherePolygonsOptions): ParseResult;
+declare function createPolyTetrahedron(options?: TetrahedronPolygonsOptions): ParseResult;
+declare function createPolyIcosahedron(options?: IcosahedronPolygonsOptions): ParseResult;
+declare function createPolyDodecahedron(options?: DodecahedronPolygonsOptions): ParseResult;
+declare function createPolyCylinder(options?: CylinderPolygonsOptions): ParseResult;
+declare function createPolyCone(options?: ConePolygonsOptions): ParseResult;
+declare function createPolyTorus(options?: TorusPolygonsOptions): ParseResult;
+
 declare function injectPolyBaseStyles(doc?: Document): void;
 
-export { type PolyControlsAnimateOptions, type PolyControlsBaseOptions, type PolyControlsCamera, type PolyControlsChangeEvent, type PolyControlsEvent, type PolyControlsHandle, type PolyControlsInteractionEvent, type PolyControlsListener, type PolyFirstPersonControlsHandle, type PolyFirstPersonControlsOptions, type PolyMapControlsHandle, type PolyMapControlsOptions, PolyMeshHandle, type PolyOrbitControlsHandle, type PolyOrbitControlsOptions, PolySceneHandle, type PolySelectOptions, type PolySelectionHandle, type PolyTransformControlsHandle, type PolyTransformControlsObjectChangeEvent, type PolyTransformControlsOptions, createPolyFirstPersonControls, createPolyMapControls, createPolyOrbitControls, createSelect, createTransformControls, injectPolyBaseStyles };
+export { PolyControlsBaseOptions, PolyControlsEvent, PolyControlsHandle, PolyControlsListener, type PolyFirstPersonControlsHandle, type PolyFirstPersonControlsOptions, type PolyMapControlsHandle, type PolyMapControlsOptions, PolyMeshHandle, type PolyRenderStats, type PolyRenderStatsOptions, type PolyRenderSurfaceLeafCounts, PolySceneHandle, PolySceneOptions, PolySceneSnapshotError, type PolySceneSnapshotErrorCode, type PolySelectOptions, type PolySelectionHandle, type PolyTransformControlsHandle, type PolyTransformControlsObjectChangeEvent, type PolyTransformControlsOptions, type RenderTextureAtlasAsyncResult, type RenderTextureAtlasOptions, type RenderTextureAtlasResult, type RenderedPoly, buildAtlasPages, collectPolyRenderStats, createPolyBox, createPolyCone, createPolyCylinder, createPolyDodecahedron, createPolyFirstPersonControls, createPolyIcosahedron, createPolyMapControls, createPolyOctahedron, createPolyPlane, createPolyRing, createPolyScene, createPolySphere, createPolyTetrahedron, createPolyTorus, createSelect, createTransformControls, exportPolySceneSnapshot, filterAtlasPlans, getSolidPaintDefaults, getSolidPaintDefaultsFromPlans, injectPolyBaseStyles, isBorderShapeSupported, isSolidTriangleSupported, packTextureAtlasPlansWithScale, renderPolygonsWithStableTriangles, renderPolygonsWithTextureAtlas, renderPolygonsWithTextureAtlasAsync, updatePolygonsWithStableTopology, updatePolygonsWithStableTriangles, updateStableTriangleFrame };

package/dist/index.d.ts

@@ -1,99 +1,106 @@
-import { P as PolySceneHandle, a as PolyMeshHandle } from './PolySelectElement-Tvsmhx2m.js';
-export { b as PolyCameraOptions, c as PolyMapControlsElement, d as PolyMeshElement, e as PolyMeshTransform, f as PolyOrbitControlsElement, g as PolyOrthographicCameraElement, h as PolyOrthographicCameraHandle, i as PolyOrthographicCameraOptions, j as PolyPerspectiveCameraElement, k as PolyPerspectiveCameraHandle, l as PolyPerspectiveCameraOptions, m as PolyPolygonElement, n as PolyRenderStrategiesOption, o as PolyRenderStrategy, p as PolySceneElement, q as PolySceneOptions, r as PolySelectElement, s as PolyTransformControlsElement, T as TextureQuality, t as createPolyOrthographicCamera, u as createPolyPerspectiveCamera, v as createPolyScene } from './PolySelectElement-Tvsmhx2m.js';
-import { Vec3 } from '@layoutit/polycss-core';
+import { P as PolySceneOptions, a as PolySceneHandle, b as PolyControlsHandle, c as PolyControlsBaseOptions, d as PolyControlsEvent, e as PolyControlsListener, f as PolyMeshHandle } from './PolyShapeElements-BNHvErQF.js';
+export { g as PolyBoxElement, h as PolyCameraElement, i as PolyCameraOptions, j as PolyConeElement, k as PolyControlsAnimateOptions, l as PolyControlsCamera, m as PolyControlsChangeEvent, n as PolyControlsInteractionEvent, o as PolyCylinderElement, p as PolyDodecahedronElement, q as PolyFirstPersonControlsElement, r as PolyIcosahedronElement, s as PolyIframeElement, t as PolyMapControlsElement, u as PolyMeshElement, v as PolyMeshTransform, w as PolyOctahedronElement, x as PolyOrbitControlsElement, y as PolyOrbitControlsHandle, z as PolyOrbitControlsOptions, A as PolyOrthographicCameraElement, B as PolyOrthographicCameraHandle, C as PolyOrthographicCameraOptions, D as PolyPerspectiveCameraElement, E as PolyPerspectiveCameraHandle, F as PolyPerspectiveCameraOptions, G as PolyPlaneElement, H as PolyPolygonElement, I as PolyRingElement, J as PolySceneElement, K as PolySelectElement, L as PolySphereElement, M as PolyTetrahedronElement, N as PolyTorusElement, O as PolyTransformControlsElement, Q as createPolyCamera, R as createPolyOrbitControls, S as createPolyOrthographicCamera, T as createPolyPerspectiveCamera } from './PolyShapeElements-BNHvErQF.js';
+import * as _layoutit_polycss_core from '@layoutit/polycss-core';
+import { PolyDirectionalLight, PolyAmbientLight, PolyTextureLightingMode, TextureAtlasPlan, TextureQuality, PackedAtlas, PackedPage, TextureAtlasPage, PolyRenderStrategy, SolidPaintDefaults, Polygon, SolidTriangleFrame, Vec3, BoxPolygonsOptions, ParseResult, ConePolygonsOptions, CylinderPolygonsOptions, DodecahedronPolygonsOptions, IcosahedronPolygonsOptions, OctahedronPolygonsOptions, PlanePolygonsOptions, RingPolygonsOptions, SpherePolygonsOptions, TetrahedronPolygonsOptions, TorusPolygonsOptions } from '@layoutit/polycss-core';
 export * from '@layoutit/polycss-core';
+export { ComputeTextureAtlasPlanOptions, PackedAtlas, PackedPage, PackedTextureAtlasEntry, PolyRenderStrategiesOption, PolyRenderStrategy, ParseResult as PolyShapeResult, SolidPaintDefaults, SolidTriangleFrame, TextureAtlasPage, TextureAtlasPlan, TextureQuality, buildTextureEdgeRepairSets, computeTextureAtlasPlanPublic, cssBorderShapeForPlan, formatBorderShapeEntryMatrix, formatCssLengthPx, formatMatrix3d, formatSolidQuadEntryMatrix, isFullRectSolid, isProjectiveQuadPlan, isSolidTrianglePlan } from '@layoutit/polycss-core';
 
-/**
- * Shared types, constants, and utilities for orbit/map controls factories.
- * Not part of the public API surface — use createPolyOrbitControls or
- * createPolyMapControls.
- */
-
-interface PolyControlsAnimateOptions {
-    /**
-     * Rotation rate in degrees per 60 Hz-equivalent frame. The tick is
-     * dt-clamped so 0.3 deg/frame ≈ 18 deg/sec on every refresh rate.
-     * Default: 0.3.
-     */
-    speed?: number;
-    /** Rotation axis. Default: "y" (yaw, rotates around vertical world Z). */
-    axis?: "x" | "y";
-    /** Halt the loop while a pointer drag is in progress. Default: true. */
-    pauseOnInteraction?: boolean;
-}
-interface PolyControlsBaseOptions {
-    /** Pointer-drag. Default: true. */
-    drag?: boolean;
-    /** Wheel / pinch zoom. Default: true. */
-    wheel?: boolean;
+interface RenderTextureAtlasOptions {
+    doc?: Document;
+    tileSize?: number;
+    layerElevation?: number;
+    directionalLight?: PolyDirectionalLight;
+    ambientLight?: PolyAmbientLight;
+    textureLighting?: PolyTextureLightingMode;
     /**
-     * When `true`, wheel events change `distance` (camera pull-back in CSS px)
-     * instead of `zoom`. Mirrors Three.js OrbitControls dolly behaviour.
-     * Default: false (zoom mode).
+     * Atlas bitmap budget and CSS sprite size. Numeric values are clamped to
+     * 0.1..1 and keep the 64px sprite. Omitted / `"auto"` picks a raster scale
+     * from packed atlas area, caps oversized runtime bitmaps by side length and
+     * decoded-memory budget, and uses a 128px sprite on desktop-class documents
+     * or a 64px sprite on mobile-class documents.
      */
-    dolly?: boolean;
+    textureQuality?: _layoutit_polycss_core.TextureQuality;
+    solidPaintDefaults?: _layoutit_polycss_core.SolidPaintDefaults;
+    strategies?: _layoutit_polycss_core.PolyRenderStrategiesOption;
     /**
-     * Drag-direction inversion. `false` = natural, `true` = invert (×-1),
-     * a number multiplies sensitivity (negative inverts). Default: false.
+     * Indices of polygons that the directional light cannot reach (precomputed
+     * by createPolyScene via {@link computeLightVisibility}). Atlas + solid
+     * planning forces directScale to 0 for these polys so they render with
+     * ambient-only color, matching what a shadow-map pass would output.
      */
-    invert?: boolean | number;
-    /** Minimum CSS zoom. Default: 0.1. */
-    minZoom?: number;
-    /** Maximum CSS zoom. Default: 10. */
-    maxZoom?: number;
-    /** Minimum dolly distance in CSS pixels. Default: 0. Only used when `dolly: true`. */
-    minDistance?: number;
-    /** Maximum dolly distance in CSS pixels. Default: Infinity. Only used when `dolly: true`. */
-    maxDistance?: number;
-    /** Auto-rotate. Pass false (or omit) to disable. */
-    animate?: false | PolyControlsAnimateOptions;
+    lightOccludedPolyIndices?: ReadonlySet<number>;
 }
-interface PolyControlsCamera {
-    rotX: number;
-    rotY: number;
-    zoom: number;
-    target: Vec3;
-    distance: number;
+interface RenderedPoly {
+    polygonIndex: number;
+    element: HTMLElement;
+    kind?: "atlas" | "solid" | "border" | "corner" | "triangle";
+    plan?: _layoutit_polycss_core.TextureAtlasPlan;
+    dispose(): void;
 }
-interface PolyControlsChangeEvent {
-    type: "change";
-    camera: PolyControlsCamera;
+interface RenderTextureAtlasResult {
+    rendered: RenderedPoly[];
+    dispose(): void;
+    /**
+     * Resolves once every textured `<s>` leaf has its `background-image`
+     * applied (i.e. the atlas canvas → Blob → URL chain has completed and
+     * the apply-bg pass has run). For meshes with no textured leaves this
+     * resolves immediately. Callers doing stale-while-revalidate swaps
+     * await this before disposing the previous render — without it, the
+     * fresh leaves mount with empty backgrounds and the prior frame's
+     * bitmaps would be needed underneath to avoid a transparent flash.
+     */
+    pagesReady?: Promise<void>;
 }
-interface PolyControlsInteractionEvent {
-    type: "start" | "end";
-    camera: PolyControlsCamera;
-}
-type PolyControlsEvent = PolyControlsChangeEvent | PolyControlsInteractionEvent;
-type PolyControlsListener<E extends PolyControlsEvent = PolyControlsEvent> = (event: E) => void;
-interface PolyControlsHandle {
-    update(partial: PolyControlsBaseOptions): void;
-    resume(): void;
-    pause(): void;
-    destroy(): void;
-    addEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
-        type: T;
-    }>>): void;
-    removeEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
-        type: T;
-    }>>): void;
-    hasEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
-        type: T;
-    }>>): boolean;
+interface RenderTextureAtlasAsyncResult extends RenderTextureAtlasResult {
+    solidPaintDefaults: _layoutit_polycss_core.SolidPaintDefaults;
 }
 
+declare function packTextureAtlasPlansWithScale(plans: Array<TextureAtlasPlan | null>, textureQualityInput: TextureQuality | undefined, doc: Document | null | undefined): {
+    packed: PackedAtlas;
+    atlasScale: number;
+    atlasCanonicalSize: number;
+};
+
+declare function buildAtlasPages(pages: PackedPage[], textureLighting: PolyTextureLightingMode, doc: Document, atlasScale: number, isCancelled: () => boolean): Promise<TextureAtlasPage[]>;
+
 /**
- * createPolyOrbitControls — orbit-mode camera input for a PolyScene.
+ * Compute the dominant paint defaults from an already-computed array of plans.
  *
- * Left-drag rotates rotX / rotY around the target (orbit). Wheel zooms or
- * dollies. Mirrors Three.js OrbitControls semantics.
- *
- * For map/pan semantics (left-drag pans, right-drag orbits) use
- * `createPolyMapControls` instead.
+ * React and Vue compute plans first (to drive the atlas packing), then pass
+ * the plan array here so they don't need access to the raw polygon list.
+ * Requires access to a Document to check browser support for solid-triangle
+ * and border-shape strategies.
+ */
+declare function getSolidPaintDefaultsFromPlans(plans: Array<TextureAtlasPlan | null>, textureLighting: PolyTextureLightingMode, disabled?: ReadonlySet<PolyRenderStrategy>, doc?: Document | null): SolidPaintDefaults;
+/**
+ * Returns true when the browser supports the `border-shape` CSS property and
+ * the pointer/hover media queries indicate a fine-pointer device (desktop-class).
+ * Falls back to a globalThis-based check when no Document is available.
+ */
+declare function isBorderShapeSupported(doc?: Document | null): boolean;
+/**
+ * Returns true when the browser renders CSS border-trick triangles correctly.
+ * WebKit/Safari renders them incorrectly when transformed — this check gates
+ * the `<u>` strategy path.
+ */
+declare function isSolidTriangleSupported(doc?: Document | null): boolean;
+/**
+ * Filter a plan array to the subset that needs atlas packing, given the active
+ * render strategies and texture-lighting mode. Plans excluded from the atlas
+ * will be rendered via `<b>`, `<i>`, or `<u>` by the framework components.
  */
+declare function filterAtlasPlans(plans: Array<TextureAtlasPlan | null>, textureLighting: PolyTextureLightingMode, disabled: ReadonlySet<PolyRenderStrategy>, doc?: Document | null): Array<TextureAtlasPlan | null>;
+
+declare function getSolidPaintDefaults(polygons: Polygon[], options?: RenderTextureAtlasOptions): SolidPaintDefaults;
+declare function renderPolygonsWithTextureAtlas(polygons: Polygon[], options?: RenderTextureAtlasOptions): RenderTextureAtlasResult;
+declare function renderPolygonsWithTextureAtlasAsync(polygons: Polygon[], options?: RenderTextureAtlasOptions, shouldCancel?: () => boolean): Promise<RenderTextureAtlasAsyncResult>;
+declare function updateStableTriangleFrame(rendered: RenderedPoly[], polygons: Polygon[], frame: SolidTriangleFrame, options?: RenderTextureAtlasOptions): boolean;
+declare function updatePolygonsWithStableTopology(rendered: RenderedPoly[], polygons: Polygon[], options?: RenderTextureAtlasOptions): boolean;
+
+declare function renderPolygonsWithStableTriangles(polygons: Polygon[], options?: RenderTextureAtlasOptions): RenderTextureAtlasResult | null;
+declare function updatePolygonsWithStableTriangles(rendered: RenderedPoly[], polygons: Polygon[], options?: RenderTextureAtlasOptions): RenderTextureAtlasResult | null;
 
-type PolyOrbitControlsOptions = PolyControlsBaseOptions;
-type PolyOrbitControlsHandle = PolyControlsHandle;
-declare function createPolyOrbitControls(scene: PolySceneHandle, options?: PolyOrbitControlsOptions): PolyOrbitControlsHandle;
+declare function createPolyScene(host: HTMLElement, options: PolySceneOptions): PolySceneHandle;
 
 /**
  * createPolyMapControls — map/pan-mode camera input for a PolyScene.
@@ -191,7 +198,7 @@ interface PolyFirstPersonControlsHandle {
 declare function createPolyFirstPersonControls(scene: PolySceneHandle, options?: PolyFirstPersonControlsOptions): PolyFirstPersonControlsHandle;
 
 /**
- * createSelect — additive selection layer for vanilla polycss scenes.
+ * createSelect — additive selection layer for vanilla PolyCSS scenes.
  * Mirrors the React `<Select>` API: tracks one or more selected
  * meshes, fires `onChange` whenever the set changes, supports
  * single-click toggle (re-clicking the selected mesh deselects it),
@@ -295,6 +302,60 @@ interface PolyTransformControlsHandle {
 }
 declare function createTransformControls(scene: PolySceneHandle, options?: PolyTransformControlsOptions): PolyTransformControlsHandle;
 
+interface PolyRenderSurfaceLeafCounts {
+    quad: number;
+    clippedSolid: number;
+    atlas: number;
+    stableTriangle: number;
+}
+interface PolyRenderStats {
+    polygonCount: number;
+    mountedPolygonLeafCount: number;
+    shadowLeafCount: number;
+    surfaceLeafCounts: PolyRenderSurfaceLeafCounts;
+    bucketCount: number;
+}
+interface PolyRenderStatsOptions {
+    polygonCount?: number;
+    /**
+     * Optional subtree selector for diagnostics that only want model leaves and
+     * not helpers/floors/gizmos sharing the same scene root.
+     */
+    scopeSelector?: string;
+}
+declare function collectPolyRenderStats(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyRenderStats;
+
+type PolySceneSnapshotErrorCode = "INVALID_TARGET" | "SCENE_NOT_FOUND" | "ASSET_INLINE_FAILED";
+declare class PolySceneSnapshotError extends Error {
+    readonly code: PolySceneSnapshotErrorCode;
+    readonly url?: string;
+    constructor(code: PolySceneSnapshotErrorCode, message: string, url?: string);
+}
+/**
+ * Serialize the current rendered PolyCSS DOM into a standalone HTML document.
+ * The snapshot is intentionally static: it preserves the scene's current DOM,
+ * inlines CSS image assets, and emits no scripts or PolyCSS runtime imports.
+ */
+declare function exportPolySceneSnapshot(target: Element): Promise<string>;
+
+/**
+ * Primitive shape factories — thin wrappers over the polygon generators in
+ * @layoutit/polycss-core. Each returns a `ParseResult`-compatible object so
+ * it composes directly with `scene.add(createPolyBox({ size: 100 }))`.
+ */
+
+declare function createPolyBox(options?: BoxPolygonsOptions): ParseResult;
+declare function createPolyPlane(options: PlanePolygonsOptions): ParseResult;
+declare function createPolyRing(options: RingPolygonsOptions): ParseResult;
+declare function createPolyOctahedron(options: OctahedronPolygonsOptions): ParseResult;
+declare function createPolySphere(options?: SpherePolygonsOptions): ParseResult;
+declare function createPolyTetrahedron(options?: TetrahedronPolygonsOptions): ParseResult;
+declare function createPolyIcosahedron(options?: IcosahedronPolygonsOptions): ParseResult;
+declare function createPolyDodecahedron(options?: DodecahedronPolygonsOptions): ParseResult;
+declare function createPolyCylinder(options?: CylinderPolygonsOptions): ParseResult;
+declare function createPolyCone(options?: ConePolygonsOptions): ParseResult;
+declare function createPolyTorus(options?: TorusPolygonsOptions): ParseResult;
+
 declare function injectPolyBaseStyles(doc?: Document): void;
 
-export { type PolyControlsAnimateOptions, type PolyControlsBaseOptions, type PolyControlsCamera, type PolyControlsChangeEvent, type PolyControlsEvent, type PolyControlsHandle, type PolyControlsInteractionEvent, type PolyControlsListener, type PolyFirstPersonControlsHandle, type PolyFirstPersonControlsOptions, type PolyMapControlsHandle, type PolyMapControlsOptions, PolyMeshHandle, type PolyOrbitControlsHandle, type PolyOrbitControlsOptions, PolySceneHandle, type PolySelectOptions, type PolySelectionHandle, type PolyTransformControlsHandle, type PolyTransformControlsObjectChangeEvent, type PolyTransformControlsOptions, createPolyFirstPersonControls, createPolyMapControls, createPolyOrbitControls, createSelect, createTransformControls, injectPolyBaseStyles };
+export { PolyControlsBaseOptions, PolyControlsEvent, PolyControlsHandle, PolyControlsListener, type PolyFirstPersonControlsHandle, type PolyFirstPersonControlsOptions, type PolyMapControlsHandle, type PolyMapControlsOptions, PolyMeshHandle, type PolyRenderStats, type PolyRenderStatsOptions, type PolyRenderSurfaceLeafCounts, PolySceneHandle, PolySceneOptions, PolySceneSnapshotError, type PolySceneSnapshotErrorCode, type PolySelectOptions, type PolySelectionHandle, type PolyTransformControlsHandle, type PolyTransformControlsObjectChangeEvent, type PolyTransformControlsOptions, type RenderTextureAtlasAsyncResult, type RenderTextureAtlasOptions, type RenderTextureAtlasResult, type RenderedPoly, buildAtlasPages, collectPolyRenderStats, createPolyBox, createPolyCone, createPolyCylinder, createPolyDodecahedron, createPolyFirstPersonControls, createPolyIcosahedron, createPolyMapControls, createPolyOctahedron, createPolyPlane, createPolyRing, createPolyScene, createPolySphere, createPolyTetrahedron, createPolyTorus, createSelect, createTransformControls, exportPolySceneSnapshot, filterAtlasPlans, getSolidPaintDefaults, getSolidPaintDefaultsFromPlans, injectPolyBaseStyles, isBorderShapeSupported, isSolidTriangleSupported, packTextureAtlasPlansWithScale, renderPolygonsWithStableTriangles, renderPolygonsWithTextureAtlas, renderPolygonsWithTextureAtlasAsync, updatePolygonsWithStableTopology, updatePolygonsWithStableTriangles, updateStableTriangleFrame };