flag-cloth 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Gregorio Vargas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,417 @@
+# flag-cloth
+
+`flag-cloth` renders an image as an interactive cloth flag with the browser's native WebGL2 canvas API. The core package has **zero runtime dependencies**.
+
+The motion comes from a real particle-and-constraint simulation: Verlet integration, structural/shear/bend constraints, aerodynamic wind forces, and iterative position solving. Canvas is only the renderer; it does not replace the simulation with sine-wave vertex animation.
+
+## Features
+
+- Dependency-free TypeScript core using native WebGL2
+- Typed-array particle, constraint, projection, normal, and triangle buffers
+- Fixed-timestep Verlet/PBD simulation independent of display frame rate
+- Aerodynamic wind applied per cloth triangle with small internal value noise
+- Structural, shear, and bend constraints
+- Edge, corner, partial-edge, and custom-point attachment
+- Mouse, pen, and touch dragging through Pointer Events
+- Perspective projection, texture deformation, fold lighting, highlights, and soft shadows
+- Independent texture and simulation resolutions
+- Vanilla and optional React APIs
+- Responsive resizing, pixel-ratio cap, offscreen pausing, and complete cleanup
+- Quality and performance rendering presets
+
+## Installation
+
+Vanilla JavaScript or TypeScript needs only the library:
+
+```bash
+pnpm add flag-cloth
+```
+
+The React entry point has React as an optional peer dependency:
+
+```bash
+pnpm add flag-cloth react
+```
+
+React DOM is normally already present in a browser React application, but `flag-cloth/react` does not import it. The package contains no Three.js, physics engine, noise package, state library, or other core runtime dependency.
+
+## Vanilla usage
+
+Give the container an explicit size:
+
+```html
+<div id="flag" style="width: min(900px, 100%); height: 560px"></div>
+```
+
+```ts
+import { createFlagCloth } from "flag-cloth";
+
+const container = document.querySelector<HTMLElement>("#flag");
+if (!container) throw new Error("Missing #flag");
+
+const flag = createFlagCloth({
+  container,
+  texture: "/flags/dominican-republic.svg",
+  width: 3,
+  height: 2,
+  segments: { x: 32, y: 20 },
+  attachment: "left",
+  wind: {
+    direction: [1, 0.1, 0.2],
+    strength: 7,
+    turbulence: 0.35,
+    gustFrequency: 0.5,
+  },
+  simulation: {
+    damping: 0.985,
+    gravity: [0, 0, 0],
+    fixedTimeStep: 1 / 60,
+    substeps: 2,
+    constraintIterations: 6,
+  },
+  interaction: {
+    enabled: true,
+    dragRadius: 1,
+    dragStiffness: 0.9,
+  },
+  renderer: {
+    preset: "quality",
+    maxPixelRatio: 1.5,
+    transparent: true,
+  },
+});
+
+await flag.ready;
+```
+
+The instance starts automatically unless `autoStart: false` is set.
+
+```ts
+flag.start();
+flag.pause();
+flag.resume();
+flag.resize();
+flag.render();
+flag.update(1 / 60); // useful with an external animation loop
+await flag.setTexture("/flags/another-flag.webp");
+flag.setWind({ strength: 12 });
+await flag.setOptions({
+  interaction: { enabled: false },
+  material: { foldContrast: 0.55 },
+});
+flag.reset();
+flag.destroy();
+```
+
+`destroy()` cancels animation work, disconnects observers, removes Pointer Event and document listeners, clears the canvas, destroys the optional debug panel, and removes a canvas created by the library. It is safe to call more than once.
+
+## React usage
+
+```tsx
+import { useRef } from "react";
+import {
+  FlagCloth,
+  type Attachment,
+  type FlagClothInstance,
+} from "flag-cloth/react";
+
+const mastPins = {
+  points: [[0, 0], [0, 5], [0, 10], [0, 15], [0, 20]],
+} satisfies Attachment;
+
+export function FlagExample() {
+  const flagRef = useRef<FlagClothInstance>(null);
+
+  return (
+    <FlagCloth
+      ref={flagRef}
+      canvasWidth="100%"
+      canvasHeight={560}
+      texture="/flags/dominican-republic.svg"
+      width={3}
+      height={2}
+      segments={{ x: 32, y: 20 }}
+      attachment={mastPins}
+      wind={{
+        direction: [1, 0.1, 0.2],
+        strength: 7,
+        turbulence: 0.35,
+      }}
+      interaction={{ enabled: true, dragRadius: 1 }}
+      renderer={{ preset: "quality", maxPixelRatio: 1.5 }}
+      onReady={(instance) => console.log(instance.stats)}
+    />
+  );
+}
+```
+
+The wrapper creates the core instance on mount, forwards a ref to it, applies mutable prop changes with `setOptions()`, and destroys it on unmount. Particle positions and the animation loop stay outside React state, so animation does not cause React renders. The mount cleanup is safe under React Strict Mode.
+
+`width` and `height` are physical cloth dimensions in simulation units. `canvasWidth` and `canvasHeight` size the React-owned container with normal CSS values. The canvas fills that container and its backing store follows through `ResizeObserver`. You can use `className` or `style` instead; explicit canvas dimension props override the corresponding inline style dimensions.
+
+Pass stable option objects with `useMemo` when convenient. A new object is supported, but it asks the wrapper to compare and apply that option group after every React render.
+
+## How rendering works
+
+The solver remains fully three-dimensional. Each frame, the WebGL renderer:
+
+1. Uploads the current typed-array particle positions into one dynamic GPU buffer.
+2. Computes area-weighted vertex normals and uploads the reused normal buffer.
+3. Projects the indexed grid with a compact perspective camera in the vertex shader.
+4. Maps the complete image with standard UVs in a single indexed texture draw.
+5. Applies smooth diffuse fold lighting and specular highlights in the fragment shader.
+6. Draws an optional nine-sample soft silhouette shadow before the cloth.
+
+The texture is not chopped into bitmap pieces and geometry is not rebuilt each frame. The GPU interpolates UVs and vertex normals across the mesh, so there are no triangle outlines or per-triangle Canvas clips.
+
+This material model is deliberately compact. It creates readable folds and a cloth-like response using two small internal shaders, without a rendering dependency.
+
+## Texture resolution versus simulation resolution
+
+These are independent:
+
+- `texture` controls source image detail. A 2048×1365 PNG can remain visually sharp.
+- `segments` controls the number of simulated cells. `{ x: 32, y: 20 }` creates 693 particles and 1,280 rendered triangles.
+
+There is never one particle per texture pixel. Increasing image resolution does not increase constraint solving cost. Increasing `segments` does increase particle, constraint, wind, normal, buffer-upload, and indexed-triangle work.
+
+Supported sources are URL-loaded PNG, JPEG, WebP, SVG, and other formats supported by the browser's image decoder. You may also pass any ready `TexImageSource`, such as an `HTMLImageElement`, `HTMLCanvasElement`, `ImageBitmap`, or `OffscreenCanvas`:
+
+```ts
+await flag.setTexture(imageElement);
+await flag.setTexture(null); // renders material.baseColor
+```
+
+Cross-origin URLs must allow image loading according to normal browser CORS rules. URL images are loaded with `crossOrigin = "anonymous"`.
+
+## Configuration reference
+
+### Cloth and attachment
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `width` | `3` | Cloth width in simulation units. |
+| `height` | `2` | Cloth height in simulation units. |
+| `segments` | `{ x: 32, y: 20 }` | Physical grid cell count. Particle count is `(x + 1) × (y + 1)`. |
+| `attachment` | `"left"` | Pinned edge, corner, partial edge, custom points, or `"none"`. |
+| `autoStart` | `true` | Starts the internal animation loop after construction. |
+
+The exported attachment type has these exact shapes:
+
+```ts
+type EdgeAttachment = "left" | "right" | "top" | "bottom";
+type CornerAttachment =
+  | "top-left"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-right";
+
+type GridPoint = readonly [x: number, y: number];
+
+type Attachment =
+  | EdgeAttachment
+  | CornerAttachment
+  | "none"
+  | { edge: EdgeAttachment; every?: number; offset?: number }
+  | { points: ReadonlyArray<GridPoint> };
+```
+
+Examples:
+
+```ts
+attachment: "top-left"
+attachment: { edge: "left", every: 2 }
+attachment: { edge: "top", every: 3, offset: 1 }
+attachment: { points: [[0, 0], [0, 5], [4, 4]] }
+```
+
+Custom coordinates address particles in the simulation grid, not pixels, UVs, or world positions. `[0, 0]` is top-left and `[segments.x, segments.y]` is bottom-right. Decimal coordinates are rounded; out-of-range coordinates are ignored. On vertical edges, `offset` counts down from the top; on horizontal edges it counts rightward from the left. `every` defaults to `1` and `offset` defaults to `0`.
+
+The same `Attachment` type is exported by `flag-cloth/react`. Change pins at runtime with `flag.setOptions({ attachment })`; this replaces the pin mask without rebuilding cloth topology.
+
+### Wind
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `direction` | `[1, 0.08, 0.3]` | Normalized internally. |
+| `strength` | `7` | Base wind speed. |
+| `turbulence` | `0.35` | Strength of noisy gust and lateral variation. |
+| `gustFrequency` | `0.5` | Time variation rate. |
+| `spatialScale` | `0.8` | Frequency of spatial wind variation. |
+| `aerodynamicCoefficient` | `0.35` | Pressure-to-force multiplier. |
+
+For each cloth triangle, the solver calculates its cross-product normal and area, samples local value noise, subtracts approximate triangle velocity from the wind velocity, projects that relative velocity onto the normal, and distributes the resulting pressure force among the triangle's three particles. Wind never assigns particle positions.
+
+### Simulation
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `damping` | `0.985` | Velocity retained over a 1/60-second interval. |
+| `gravity` | `[0, 0, 0]` | Acceleration vector; disabled by default for a conventional flag. |
+| `fixedTimeStep` | `1 / 60` | Stable solver step used by the accumulator. |
+| `maxFrameDelta` | `0.1` | Caps long display-frame gaps. |
+| `substeps` | `2` | Integration subdivisions per fixed step. |
+| `constraintIterations` | `6` | Structural/shear/bend solve passes per substep. |
+| `structuralStiffness` | `1` | Horizontal and vertical distance retention. |
+| `shearStiffness` | `0.9` | Diagonal distance retention. |
+| `bendStiffness` | `0.4` | Two-grid-position distance retention. |
+| `maxCorrection` | `0.25` | Per-constraint correction cap; `0` disables the cap. |
+| `mass` | `1` | Total cloth mass, independent of grid density. |
+
+Stiffness is converted to an iteration-independent correction so changing iteration count does not multiply the intended stiffness directly.
+
+### Interaction
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Enables mouse, pen, and touch dragging. |
+| `dragRadius` | `1` | Grid-space radius of particles affected around the grabbed point. |
+| `dragStiffness` | `0.9` | Strength of the temporary positional constraint. |
+| `maxDragDistance` | `4` | Maximum distance from the original grab position; `0` is unlimited. |
+| `allowPinned` | `false` | Allows temporarily moving attached particles. |
+| `releaseImpulse` | `[0, 0, 0]` | Optional velocity impulse added on release. |
+
+Pointer selection uses the renderer's projected indexed triangles. The hit triangle's nearest barycentric vertex becomes the selected particle, and neighboring particles inside `dragRadius` receive weighted temporary constraints. The target moves on a camera-facing plane. Pointer capture keeps the drag active outside the canvas; release restores free motion while retaining the Verlet velocity naturally.
+
+### Renderer and material
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `renderer.preset` | `"quality"` | Applies a complete profile. `quality` uses a 1.5× pixel cap, shadows, highlights, and per-frame normals; `performance` uses 1×, no shadows or highlights, and every-second-frame normals. Explicit renderer overrides still win. |
+| `renderer.maxPixelRatio` | `1.5` | Caps backing-store resolution. Never uses device pixel ratio uncapped. |
+| `renderer.alpha` | `true` | Requests an alpha-enabled WebGL2 context. Construction-time only. |
+| `renderer.antialias` | `true` | Requests browser multisample antialiasing. Construction-time only. |
+| `renderer.desynchronized` | `false` | Requests a desynchronized context when supported. Construction-time only. |
+| `renderer.powerPreference` | `"high-performance"` | GPU preference supplied during context creation. Construction-time only. |
+| `renderer.textureFiltering` | `"linear"` | Mipmapped linear or nearest-neighbor texture filtering. |
+| `renderer.transparent` | `true` | Clears to transparency instead of filling a background. |
+| `renderer.backgroundColor` | `"transparent"` | Fill used when `transparent` is false. |
+| `renderer.shadows` | `true` | Enables the soft silhouette shadow. The performance profile defaults this to `false`, but it can be overridden. |
+| `renderer.shadingUpdateInterval` | `1` | Recomputes normals every N rendered frames. |
+| `material.baseColor` | `"#f2f4f3"` | Cloth fill when no texture is set. |
+| `material.ambient` | `0.58` | Minimum material brightness. |
+| `material.diffuse` | `0.55` | Directional fold lighting strength. |
+| `material.specular` | `0.16` | Highlight strength in quality mode. |
+| `material.shininess` | `18` | Highlight concentration. |
+| `material.foldContrast` | `0.42` | Dark/light fold contrast. |
+| `material.shadowColor` | `"rgba(0, 0, 0, 0.3)"` | Soft silhouette shadow color. |
+| `material.shadowBlur` | `18` | Shadow blur in CSS pixels. |
+| `material.shadowOffsetX/Y` | `10 / 12` | Shadow offset in CSS pixels. |
+| `lighting.enabled` | `true` | Enables material lighting overlays. |
+| `lighting.intensity` | `1` | Overall light multiplier. |
+| `lighting.direction` | `[-0.4, 0.7, 1]` | World-space light direction. |
+
+### Camera, visibility, and debug
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `camera.fov` | `40` | Vertical perspective field of view in degrees. |
+| `camera.near` / `far` | `0.01 / 100` | Projection clipping distances. |
+| `camera.position` | `null` | Camera position; `null` auto-fits the cloth. |
+| `camera.lookAt` | `[0, 0, 0]` | Camera target. |
+| `visibility.pauseWhenOffscreen` | `true` | Uses `IntersectionObserver` to pause outside the viewport. |
+| `visibility.pauseWhenDocumentHidden` | `true` | Pauses while the document is hidden. |
+| `debug` | `false` | Enables the optional lightweight debug panel. |
+| `debug.enabled` | `false` | Creates the debug overlay when using the object form. |
+| `debug.updateInterval` | `500` | Overlay refresh interval in milliseconds, clamped to at least 100. |
+
+The debug panel reports FPS, simulation time, JavaScript render-submission time, particle count, constraint count, and WebGL draw calls. It creates no panel DOM or update work unless enabled. The repository examples are clean by default; append `?debug` to an example URL to show the panel.
+
+The `advanced` group defaults to a library-created canvas and context with `externalAnimationLoop: false`. `advanced`, `autoStart`, and the WebGL context attributes `renderer.alpha`, `antialias`, `desynchronized`, and `powerPreference` are construction-time options. They are intentionally unavailable through `FlagClothUpdateOptions`.
+
+## Performance recommendations
+
+- Start at `{ x: 32, y: 20 }`; raise it only when silhouette smoothness needs it.
+- Use `renderer.preset: "performance"` for several simultaneous flags or mobile-first pages.
+- Keep `maxPixelRatio` at `1`–`1.5`; fragment-shader cost scales with backing-store area.
+- Lower `constraintIterations` before lowering substeps if the cloth is stable enough.
+- Quality uses ten draw calls: nine soft-shadow samples and one cloth draw. Performance mode uses one cloth draw.
+- Keep offscreen and hidden-document pausing enabled.
+- Read `instance.stats` or enable `debug` while profiling the actual target devices.
+
+At the default 32×20 grid, the simulation holds 693 particles, 3,890 precomputed constraints, and 1,280 indexed triangles. Hot loops use numeric typed arrays, avoid callback-heavy array methods, and reuse normal and GPU-upload buffers. CPU projection runs only when pointer hit-testing needs it. JavaScript creates no per-particle or per-constraint objects each frame.
+
+## Custom canvas and animation loop
+
+The normal API creates and sizes its own canvas. Advanced integration can supply a caller-owned canvas or WebGL2 context:
+
+```ts
+const canvas = document.querySelector<HTMLCanvasElement>("#shared-canvas");
+if (!canvas) throw new Error("Missing canvas");
+
+const flag = createFlagCloth({
+  container: canvas.parentElement!,
+  texture: imageElement,
+  advanced: {
+    canvas,
+    context: canvas.getContext("webgl2")!,
+    externalAnimationLoop: true,
+  },
+  autoStart: true,
+});
+
+let previous = performance.now();
+function frame(now: number) {
+  flag.update((now - previous) / 1000, true);
+  previous = now;
+  requestAnimationFrame(frame);
+}
+requestAnimationFrame(frame);
+```
+
+When a canvas or context is provided, the caller owns that resource and must place it in the document. `destroy()` removes listeners, deletes the library's GPU buffers, program, texture, and vertex array, and clears the canvas, but does not remove it. A WebGL context is stateful, so coordinate externally before issuing other commands into the same context.
+
+## Browser support
+
+The library targets modern browsers with:
+
+- WebGL2 and GLSL ES 3.00 shaders
+- ES modules and typed arrays
+- Pointer Events and pointer capture
+- `requestAnimationFrame`
+- `ResizeObserver` for automatic sizing
+- `IntersectionObserver` for optional offscreen pausing
+
+Current Chromium, Firefox, and Safari releases provide these APIs. The simulation itself can be unit-tested without WebGL.
+
+## Examples and development
+
+This repository includes:
+
+- `examples/vanilla` — TypeScript API and live controls
+- `examples/react` — React wrapper under Strict Mode
+- `examples/stress` — multiple flags and resolution controls
+
+```bash
+pnpm install
+pnpm dev
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm examples:build
+pnpm bench
+```
+
+The tests cover pinned and forced particles, all constraint families, long-run finiteness, fixed-step delta capping, reset, drag solving, Pointer Event cleanup, and instance lifecycle cleanup.
+
+## Publishing
+
+1. Choose a semver version and update `package.json`.
+2. Run `pnpm typecheck && pnpm test && pnpm build && pnpm examples:build`.
+3. Inspect the package with `pnpm pack --dry-run`.
+4. Publish with `pnpm publish --access public`.
+
+The package exports `flag-cloth` and `flag-cloth/react`. Only `dist`, this README, and the license are published. React remains external and optional; the core entry has no peer or runtime dependency.
+
+## Known limitations
+
+- The compact lighting shader is visually motivated rather than physically based.
+- The soft shadow uses a small screen-space sample kernel; it is not ray-traced self-shadowing.
+- The cloth solver is CPU-driven. Prefer several hundred or a few thousand particles, not GPU-compute-sized grids.
+- There is no collision, tearing, self-collision, pole model, or rigid-body coupling in the first version.
+- URL texture loading follows browser image-decoding and CORS behavior.
+- A WebGPU compute solver could be added later, but it would be a separate optional path rather than complicating the readable CPU solver.
+
+## License
+
+MIT