@bigmistqke/view.gl 0.1.2 → 0.1.4

package/README.md

@@ -1,34 +1,55 @@
-# view.gl
+# 👁️ @bigmistqke/view.gl
 
-Minimal library for WebGL shader resource management with type-safe GLSL template literals.
+🔧 Minimal library for managing WebGL uniforms / (interleaved) attributes / buffers / ...
+
+- schema-based resource management [`view-gl`](#️-viewgl)
+- type-safe GLSL template literals to compose schemas [`view-gl/tag`](#️-viewgltag)
 
 ## Table of Contents
 
-- [View](#view)
-  - [Basic Usage](#basic-usage)
-  - [View Types](#view-types)
-    - [uniformView](#uniformview)
-    - [attributeView](#attributeview)
-    - [interleavedAttributeView](#interleavedattributeview)
-    - [bufferView](#bufferview)
-  - [Drawing Examples](#drawing-examples)
-    - [Regular Drawing](#regular-drawing)
-    - [Instanced Drawing](#instanced-drawing)
-- [Tag](#tag)
-  - [Basic Usage](#basic-usage-1)
-  - [Template Features](#template-features)
-  - [Tag Functions](#tag-functions)
-  - [Symbol Support in Templates](#symbol-support)
-- [Utils](#utils)
-  - [Create Program](#createprogram)
-  - [Create Texture](#createtexture)
-  - [Create Frame Buffer](#createframebuffer)
-
-## View
-
-The view system provides type-safe WebGL resource management for uniforms, attributes, and buffers.
-
-### Basic Usage
+- [📦 Install](#-install)
+- [👁️ view.gl](#️-viewgl)
+  - [🚀 Basic Usage](#-basic-usage)
+  - [👁️ view](#️-view)
+  - [👀 Resource Views](#-resource-views)
+    - [🎯 uniformView](#-uniformview)
+    - [📝 attributeView](#-attributeview)
+    - [🔗 interleavedAttributeView](#-interleavedattributeview)
+    - [🗂️ bufferView](#-bufferview)
+- [🏷️ view.gl/tag](#️-viewgltag)
+  - [🚀 Basic Usage](#-basic-usage-1)
+  - [📝 glsl](#-glsl)
+    - [🧩 GLSL Fragment](#-glsl-fragment)
+    - [🔒 Symbol Scoping](#-symbol-scoping)
+    - [WebGL Version Support](#webgl-version-support)
+  - [⚙️ Resource Tags](#️-resource-tags)
+    - [🎯 uniform[kind](name, options?)](#-uniformkindname-options)
+    - [📝 attribute[kind](name, options?)](#-attributekindname-options)
+    - [🔗 interleave(name, layout, options?)](#-interleavename-layout-options)
+  - [⚙️ compile(gl, vertex, fragment)](#️-compilegl-vertex-fragment)
+- [🛠️ Utils](#️-utils)
+  - [🏗️ createProgram](#️-createprogram)
+  - [🖼️ createTexture](#️-createtexture)
+  - [🖥️ createFramebuffer](#️-createframebuffer)
+- [🔍 WebGL Type Compatibility](#-webgl-type-compatibility)
+  - [🎯 Uniform Types](#-uniform-types)
+  - [📝 Attribute Types](#-attribute-types)
+
+## 📦 Install
+
+```shell
+npm install @bigmistqke/view.gl
+# or
+pnpm add @bigmistqke/view.gl
+# or
+yarn add @bigmistqke/view.gl
+```
+
+## 👁️ view.gl
+
+The view system provides type-safe WebGL resource management for uniforms, attributes, and buffers
+
+### 🚀 Basic Usage
 
 ```typescript
 import { view } from '@bigmistqke/view.gl'
@@ -56,26 +77,74 @@ attributes.position.set(positionData)
 attributes.position.bind()
 ```
 
-### View Types
+### 👁️ view
 
-Each view type can be imported individually too.
+The `view()` function creates type-safe WebGL resource managers from a schema.
 
 ```typescript
-import {
-  uniformView,
-  attributeView,
-  interleavedAttributeView,
-  bufferView,
-} from '@bigmistqke/view.gl'
+const { uniforms, attributes, buffers } = view(gl, program, schema)
 ```
 
-#### uniformView
+**Parameters:**
 
-Manages shader uniform variables.
+- `gl`: WebGL rendering context
+- `program`: Compiled WebGL program
+- `schema`: Resource definitions object
+
+**Returns:**
+
+- `uniforms`: Type-safe uniform setters
+- `attributes`: Attribute managers with buffer handling
+- `buffers`: Generic buffer managers
+
+**ViewSchema:**
+The complete schema object that defines all WebGL resources. Contains optional mappings for uniforms, attributes, interleaved attributes, and buffers.
+
+<details>
+<summary>TypeScript Types</summary>
 
 ```typescript
-import { uniformView } from '@bigmistqke/view.gl'
+interface ViewSchema {
+  uniforms?: Record<string | symbol, UniformOptions>
+  attributes?: Record<string | symbol, AttributeOptions>
+  interleavedAttributes?: Record<string | symbol, InterleavedAttributeOptions>
+  buffers?: Record<string | symbol, BufferOptions>
+}
+
+interface UniformOptions {
+  kind: UniformKind
+  size?: number // For array uniforms
+}
+
+interface AttributeOptions {
+  kind: AttributeKind
+  instanced?: boolean
+  buffer?: WebGLBuffer
+}
+
+interface InterleavedAttributeOptions {
+  layout: Array<{ key: string | symbol; kind: AttributeKind }>
+  instanced?: boolean
+  buffer?: WebGLBuffer
+}
+
+interface BufferOptions {
+  target: 'ARRAY_BUFFER' | 'ELEMENT_ARRAY_BUFFER'
+  usage?: 'STATIC_DRAW' | 'DYNAMIC_DRAW' | 'STREAM_DRAW'
+}
+```
+
+</details>
+
+### 👀 Resource Views
 
+Each view type can be imported individually.
+
+#### 🎯 uniformView
+
+Manages shader uniform variables.
+
+```typescript
 const uniforms = uniformView(gl, program, {
   time: { kind: 'float' },
   lights: { kind: 'vec3', size: 8 }, // Array uniform: vec3[8]
@@ -84,52 +153,118 @@ const uniforms = uniformView(gl, program, {
 
 uniforms.time.set(performance.now())
 uniforms.lights.set(lightData) // Takes Float32Array for array uniforms
-uniforms.transform.set(transformMatrix)
 ```
 
-**Settings:**
+**UniformSchema:**
+A mapping of uniform names to their configuration. Each uniform has a GLSL type and optional array size.
 
-- `kind`: GLSL type (`'float'`, `'vec2'`, `'mat4'`, `'sampler2D'`, etc.)
-- `size`: Array size (optional) - converts uniform to array type with Float32Array setter
+```typescript
+{
+  time: { kind: 'float' },
+  transform: { kind: 'mat4' },
+  lights: { kind: 'vec3', size: 8 }, // Array uniform
+}
+```
 
-#### attributeView
+- `kind`: GLSL type (see [Uniform Types](#-uniform-types) for full list and WebGL compatibility)
+- `size`: Array size (optional) - converts uniform to array type
 
-Manages vertex attributes with buffer creation, binding, and data management.
+<details>
+<summary>TypeScript Types</summary>
 
 ```typescript
-import { attributeView } from '@bigmistqke/view.gl'
+type UniformKind =
+  | 'float'
+  | 'int'
+  | 'bool'
+  | 'vec2'
+  | 'vec3'
+  | 'vec4'
+  | 'ivec2'
+  | 'ivec3'
+  | 'ivec4'
+  | 'bvec2'
+  | 'bvec3'
+  | 'bvec4'
+  | 'mat2'
+  | 'mat3'
+  | 'mat4'
+  | 'sampler2D'
+  | 'samplerCube'
+
+interface UniformOptions {
+  kind: UniformKind
+  size?: number // Creates array uniform with Float32Array setter
+}
+
+type UniformSchema = Record<string | symbol, UniformOptions>
+```
+
+</details>
+
+#### 📝 attributeView
+
+Manages vertex attributes with automatic buffer creation and binding.
 
+```typescript
 const attributes = attributeView(gl, program, {
   position: { kind: 'vec3' },
   instanceOffset: { kind: 'vec2', instanced: true },
 })
 
-// Regular attribute for vertices
 attributes.position.set(positionData).bind()
-
-// Instanced attribute for per-instance data
 attributes.instanceOffset.set(instanceData).bind()
 
-// Draw regular geometry
-gl.drawArrays(gl.TRIANGLES, 0, 3)
-
-// Draw instanced geometry
 gl.drawArraysInstanced(gl.TRIANGLES, 0, 3, 100)
 ```
 
-**Settings:**
+**AttributeSchema:**
+A mapping of attribute names to their configuration. Each attribute has a GLSL type, optional instancing, and optional custom buffer.
 
-- `kind`: GLSL type (`'float'`, `'vec2'`, `'vec3'`, `'vec4'`, `'mat2'`, `'mat3'`, `'mat4'`, integer types)
-- `instanced`: Boolean - enables instanced rendering with `vertexAttribDivisor`
-- `buffer`: Custom WebGLBuffer (optional) - uses auto-created buffer if not provided
+```typescript
+{
+  position: { kind: 'vec3' },
+  instanceOffset: { kind: 'vec2', instanced: true },
+}
+```
 
-#### interleavedAttributeView
+- `kind`: GLSL type (see [Attribute Types](#-attribute-types) for full list and WebGL compatibility)
+- `instanced`: Boolean - enables instanced rendering
+- `buffer`: Custom WebGLBuffer (optional)
 
-Manages interleaved vertex data with automatic stride/offset calculation and VAO optimization.
+<details>
+<summary>TypeScript Types</summary>
 
 ```typescript
-import { interleavedAttributeView } from '@bigmistqke/view.gl'
+type AttributeKind =
+  | 'float'
+  | 'vec2'
+  | 'vec3'
+  | 'vec4'
+  | 'mat2'
+  | 'mat3'
+  | 'mat4'
+  | 'int'
+  | 'ivec2'
+  | 'ivec3'
+  | 'ivec4'
+
+interface AttributeOptions {
+  kind: AttributeKind
+  instanced?: boolean // Enables vertexAttribDivisor
+  buffer?: WebGLBuffer // Custom buffer, auto-created if not provided
+}
+
+type AttributeSchema = Record<string | symbol, AttributeOptions>
+```
+
+</details>
 
+#### 🔗 interleavedAttributeView
+
+Manages interleaved vertex data with automatic stride/offset calculation.
+
+```typescript
 const interleavedAttributes = interleavedAttributeView(gl, program, {
   vertexData: {
     layout: [
@@ -138,117 +273,98 @@ const interleavedAttributes = interleavedAttributeView(gl, program, {
       { key: 'uv', kind: 'vec2' },
     ],
   },
-  instanceData: {
-    layout: [
-      { key: 'instancePos', kind: 'vec2' },
-      { key: 'instanceColor', kind: 'vec3' },
-    ],
-    instanced: true,
-  },
 })
 
-// Upload interleaved data
-interleavedAttributes.vertexData.set(interleavedVertexData)
-interleavedAttributes.instanceData.set(interleavedInstanceData)
-
-// Bind all attributes in layout
-interleavedAttributes.vertexData.bind()
-interleavedAttributes.instanceData.bind()
+interleavedAttributes.vertexData.set(interleavedVertexData).bind()
 ```
 
-**Settings:**
-
-- `layout`: Array of attribute definitions with `name` and `kind`
-- `instanced`: Boolean - applies `vertexAttribDivisor` to all attributes in layout
-
-#### bufferView
-
-Manages generic WebGL buffers for various uses.
+**InterleavedAttributeSchema:**
+A mapping of interleaved buffer names to their layout configuration. Each layout defines multiple attributes packed into a single buffer.
 
 ```typescript
-import { bufferView } from '@bigmistqke/view.gl'
+{
+  vertexData: {
+    layout: [
+      { key: 'position', kind: 'vec3' },
+      { key: 'normal', kind: 'vec3' },
+      { key: 'uv', kind: 'vec2' },
+    ],
+  },
+}
+```
 
-const buffers = bufferView(gl, {
-  indices: { target: 'ELEMENT_ARRAY_BUFFER' },
-  data: { target: 'ARRAY_BUFFER', usage: 'DYNAMIC_DRAW' },
-})
+- `layout`: Array of attribute definitions with `key` and `kind` (see [Attribute Types](#-attribute-types) for WebGL compatibility)
+- `instanced`: Boolean - applies to all attributes in layout
 
-buffers.indices.set(indexData)
-buffers.indices.bind()
+<details>
+<summary>TypeScript Types</summary>
 
-buffers.data.set(dynamicData)
-buffers.data.bind()
+```typescript
+interface InterleavedAttributeOptions {
+  layout: Array<{
+    key: string | symbol
+    kind: AttributeKind
+  }>
+  instanced?: boolean // Applies vertexAttribDivisor to all attributes
+  buffer?: WebGLBuffer // Custom buffer for interleaved data
+}
+
+type InterleavedAttributeSchema = Record<string | symbol, InterleavedAttributeOptions>
 ```
 
-**Settings:**
-
-- `target`: Buffer target (`'ARRAY_BUFFER'`, `'ELEMENT_ARRAY_BUFFER'`)
-- `usage`: Usage pattern (`'STATIC_DRAW'`, `'DYNAMIC_DRAW'`, `'STREAM_DRAW'`)
+</details>
 
-### Drawing Examples
+#### 🗂️ bufferView
 
-#### Regular Drawing
+Manages generic WebGL buffers.
 
 ```typescript
-const { attributes } = view(gl, program, {
-  attributes: {
-    position: { kind: 'vec3' },
-    uv: { kind: 'vec2' },
-  },
+const buffers = bufferView(gl, {
+  indices: { target: 'ELEMENT_ARRAY_BUFFER' },
+  data: { target: 'ARRAY_BUFFER', usage: 'DYNAMIC_DRAW' },
 })
 
-attributes.position.set(vertices).bind()
-attributes.uv.set(uvData).bind()
-
-gl.drawArrays(gl.TRIANGLES, 0, vertexCount)
+buffers.indices.set(indexData).bind()
+buffers.data.set(dynamicData).bind()
 ```
 
-#### Instanced Drawing
+**BufferSchema:**
+A mapping of buffer names to their configuration. Each buffer has a target type and optional usage pattern.
 
 ```typescript
-const { attributes } = view(gl, program, {
-  attributes: {
-    position: { kind: 'vec3' },
-    instanceOffset: { kind: 'vec2', instanced: true },
-    instanceColor: { kind: 'vec3', instanced: true },
-  },
-})
-
-attributes.position.set(triangleVertices).bind()
-attributes.instanceOffset.set(instanceOffsets).bind()
-attributes.instanceColor.set(instanceColors).bind()
-
-gl.drawArraysInstanced(gl.TRIANGLES, 0, 3, instanceCount)
+{
+  indices: { target: 'ELEMENT_ARRAY_BUFFER' },
+  data: { target: 'ARRAY_BUFFER', usage: 'DYNAMIC_DRAW' },
+}
 ```
 
-### Features
+- `target`: Buffer target (`'ARRAY_BUFFER'`, `'ELEMENT_ARRAY_BUFFER'`)
+- `usage`: Usage pattern (`'STATIC_DRAW'`, `'DYNAMIC_DRAW'`, `'STREAM_DRAW'`)
 
-- **Automatic Resource Management**: Buffer creation, disposal, and cleanup
-- **Type Safety**: type checking for uniform and attribute operations
-- **WebGL Extensions**: Automatic fallback for instanced arrays and vertex array objects
-- **Memory Management**: AbortSignal support for scheduling cleanup of resources
+<details>
+<summary>TypeScript Types</summary>
 
-## Tag
+```typescript
+interface BufferOptions {
+  target: 'ARRAY_BUFFER' | 'ELEMENT_ARRAY_BUFFER'
+  usage?: 'STATIC_DRAW' | 'DYNAMIC_DRAW' | 'STREAM_DRAW' // Defaults to 'STATIC_DRAW'
+}
 
-The tag system provides GLSL template literal support with embedded schema definitions.
+type BufferSchema = Record<string | symbol, BufferOptions>
+```
 
-### Template Features
+</details>
 
-- **Embedded Resources**: Define uniforms and attributes directly in GLSL
-- **Type Safety**: Automatic schema generation from template literals
-- **WebGL Version Support**: Automatic syntax conversion for WebGL1/2
-- **Interleaved Attributes**: Multi-attribute layout support
-- **Symbol Support**: Use JavaScript symbols as keys (see [View Features](#symbol-support))
+## 🏷️ view.gl/tag
 
-### Tag Functions
+Type-safe GLSL template literals with automatic schema extraction.
 
-- `uniform[kind](name, options?)`: Define uniform variables
-- `attribute[kind](name, options?)`: Define vertex attributes
-- `interleave(name, layout, options?)`: Define interleaved attribute layouts
-- `glsl`: Template literal processor for GLSL code
-- `compile(gl, vertex, fragment)`: Compile shaders and extract schema
+- **Embedded Resources**: Define uniforms, attributes, and interleaved layouts directly in GLSL
+- **Type Inference**: Automatically infers schema types and creates type-safe view
+- **Scoped Variables**: Prevent naming collisions using symbols for private shader variables
+- **GLSL Composition**: Compose reusable GLSL fragments with automatic dependency resolution
 
-### Basic Usage
+### 🚀 Basic Usage
 
 ```typescript
 import { glsl, uniform, attribute, compile } from '@bigmistqke/view.gl/tag'
@@ -280,24 +396,233 @@ const fragmentShader = glsl`
 const { program, schema } = compile(gl, vertexShader, fragmentShader)
 ```
 
-### Symbol Support
+### 📝 glsl
+
+Template literal processor that handles GLSL code and embedded resources. Supports interpolation of:
 
-Symbols are supported as keys for uniforms, attributes, and buffers. When interpolated in glsl templates, they're automatically converted to valid GLSL identifiers. This prevents naming collisions between different shader modules and enables private scoping of shader variables.
+- **[Resource tags](#️-resource-tags)**: `uniform.*()`, `attribute.*()`, `interleave()`
+- **[Composed GLSL fragments](#-glsl-fragment)**: Reusable shader code snippets
+- **[Symbols](#-symbol-scoping)**: Scoped variable names to prevent collisions
 
 ```typescript
-const u_time = Symbol('time')
-const a_position = Symbol('position')
+import { glsl, uniform, attribute } from '@bigmistqke/view.gl/tag'
+
+const shader = glsl`
+  ${uniform.vec2('resolution')}
+  ${attribute.vec3('position')}
+  
+  void main() {
+    gl_Position = vec4(position, 1.0);
+  }
+`
+```
+
+#### 🧩 GLSL Fragment
+
+Compose reusable GLSL code fragments to build complex shaders:
+
+```typescript
+const lighting = glsl`
+  vec3 calculateLighting(vec3 normal, vec3 lightDir) {
+    float diff = max(dot(normal, lightDir), 0.0);
+    return vec3(diff);
+  }
+`
+
+const vertexShader = glsl`
+  ${attribute.vec3('position')}
+  ${attribute.vec3('normal')}
+  ${lighting}  // Include the lighting fragment
+  
+  void main() {
+    vec3 light = calculateLighting(normal, vec3(0.0, 1.0, 0.0));
+    // Use the composed function
+  }
+`
+```
+
+#### 🔒 Symbol Scoping
+
+Use JavaScript symbols to prevent naming collisions:
+
+```typescript
+const sum = Symbol('sum')
+
+const sumFragment = glsl`
+float ${sum}(float a, float b){
+  return a + b;
+}`
+
+const shader = glsl`
+${sumFragment}
+
+void main(){
+  float result = ${sum}(1.0, 2.0);
+}
+`
+```
+
+Symbols are converted to unique identifiers in the shader.
+
+#### WebGL Version Support
 
+The glsl-function supports both WebGL1 and WebGL2 syntax, automatically using the correct keywords for resource tags:
+
+```typescript
+// WebGL1 (default)
 const shader = glsl`
-  ${attribute.vec3(a_position)}
-  ${uniform.float(u_time)}
+  ${attribute.vec3('position')}  // → attribute vec3 position;
+  varying vec2 vUv;
+`
+```
+
+If the shader starts with `#version 300 es`, resource tags generate WebGL2 syntax:
+
+```typescript
+// WebGL2
+const shader = glsl`#version 300 es
+  ${attribute.vec3('position')}  // → in vec3 position;
+  out vec2 vUv;
+`
+```
+
+### ⚙️ Resource Tags
+
+Functions for defining WebGL resources directly in GLSL templates. These tags generate GLSL declarations and automatically extract type-safe schemas for use with the view system.
+
+#### 🎯 uniform[kind](name, options?)
+
+Define uniform variables in GLSL templates. Supports all GLSL uniform types (see [Uniform Types](#-uniform-types) for WebGL version compatibility).
+
+```typescript
+import { uniform, glsl } from '@bigmistqke/view.gl/tag'
+
+const shader = glsl`
+  ${uniform.float('time')}
+  ${uniform.vec3('lights', { size: 8 })} // Array uniform: vec3[8]
+  
+  void main() {
+    // Use uniforms in shader code
+  }
+`
+```
+
+**Options**:
+
+- `size`: Array size (creates array uniform with Float32Array setter)
+
+#### 📝 attribute[kind](name, options?)
+
+Define vertex attributes in GLSL templates (see [Attribute Types](#-attribute-types) for WebGL version compatibility).
+
+**Regular rendering:**
+
+```typescript
+import { attribute, glsl } from '@bigmistqke/view.gl/tag'
+
+const vertexShader = glsl`
+  ${attribute.vec3('position')}
+  
+  void main() {
+    gl_Position = vec4(position, 1.0);
+  }
+`
+```
+
+**Instanced rendering:**
+
+```typescript
+const vertexShader = glsl`
+  ${attribute.vec3('position')}
+  ${attribute.vec2('offset', { instanced: true })}
+  
+  void main() {
+    gl_Position = vec4(position + vec3(offset, 0.0), 1.0);
+  }
+`
+```
+
+**Options**:
+
+- `instanced`: Boolean - enables instanced rendering with `vertexAttribDivisor`
+- `buffer`: Custom WebGLBuffer (optional)
+
+#### 🔗 interleave(name, layout, options?)
+
+Define interleaved attribute layouts for efficient vertex data.
+
+```typescript
+import { interleave, glsl } from '@bigmistqke/view.gl/tag'
+
+const vertexShader = glsl`
+  ${interleave('vertexData', [
+    { key: 'position', kind: 'vec3' },
+    { key: 'uv', kind: 'vec2' },
+  ])}
   
   void main() {
-    gl_Position = vec4(${a_position}, ${u_time});
+    gl_Position = vec4(position + vec3(uv, 0.0), 1.0);
   }
 `
 ```
 
+**Layout format**:
+
+- `key`: Attribute name
+- `kind`: GLSL type (see [Attribute Types](#-attribute-types) for WebGL compatibility)
+
+**Options**:
+
+- `instanced`: Boolean - applies `vertexAttribDivisor` to all attributes
+
+### ⚙️ compile(gl, vertex, fragment, overrideSchema?)
+
+Compiles shaders and extracts schema from embedded resources. Returns both the compiled program and a ready-to-use view.
+
+```typescript
+import { compile } from '@bigmistqke/view.gl/tag'
+
+const { program, schema, view } = compile(gl, vertexShader, fragmentShader)
+
+// Use the view directly
+view.uniforms.time.set(performance.now())
+view.attributes.position.set(vertexData).bind()
+
+// Or access the extracted schema
+console.log(schema.uniforms) // { time: { kind: 'float' }, ... }
+console.log(schema.attributes) // { position: { kind: 'vec3' }, ... }
+```
+
+**Override Schema:**
+
+You can provide an optional override schema to enhance or override the automatically extracted schema:
+
+```typescript
+const { program, schema, view } = compile(gl, vertexShader, fragmentShader, {
+  uniforms: {
+    // Add additional uniforms not automatically inferred
+    customTime: { kind: 'float' },
+  },
+  buffers: {
+    // Add buffer definitions
+    indices: { target: 'ELEMENT_ARRAY_BUFFER' },
+  },
+})
+
+// The override schema is merged with the extracted schema
+view.uniforms.customTime.set(123.45)
+view.buffers.indices.set(indexData).bind()
+```
+
+**Returns**:
+
+- `program`: Compiled WebGL program
+- `schema`: Merged schema (extracted + override)
+- `view`: Ready-to-use view with type-safe resource access
+
+<details>
+<summary>Usage with vanilla view.gl</summary>
+
 When manually constructing GLSL strings, use `toID()` to convert symbols to valid identifiers:
 
 ```typescript
@@ -335,11 +660,11 @@ attributes[a_position].set(vertexData)
 uniforms[u_time].set(performance.now())
 ```
 
-## Utils
+</details>
 
-WebGL utilities.
+## 🛠️ Utils
 
-### createProgram
+### 🏗️ createProgram
 
 Creates and links a WebGL program from vertex and fragment shader sources.
 
@@ -349,7 +674,7 @@ import { createProgram } from '@bigmistqke/view.gl/utils'
 const program = createProgram(gl, vertexShaderSource, fragmentShaderSource)
 ```
 
-### createTexture
+### 🖼️ createTexture
 
 Creates a WebGL texture with specified parameters.
 
@@ -375,7 +700,7 @@ const texture = createTexture(
 
 Automatically validates WebGL2-only formats and provides fallbacks for WebGL1.
 
-### createFramebuffer
+### 🖥️ createFramebuffer
 
 Creates a framebuffer with attached texture for render-to-texture operations.
 
@@ -393,3 +718,76 @@ const { framebuffer, texture } = createFramebuffer(gl, {
 ```
 
 Supports color, depth, stencil, and combined depth-stencil attachments with completeness validation.
+
+## 🔍 WebGL Type Compatibility
+
+### 🎯 Uniform Types
+
+| Type                   | WebGL 1 | WebGL 2 |
+| ---------------------- | ------- | ------- |
+| `float`                | ✅      | ✅      |
+| `int`                  | ✅      | ✅      |
+| `bool`                 | ✅      | ✅      |
+| `vec2`                 | ✅      | ✅      |
+| `vec3`                 | ✅      | ✅      |
+| `vec4`                 | ✅      | ✅      |
+| `ivec2`                | ✅      | ✅      |
+| `ivec3`                | ✅      | ✅      |
+| `ivec4`                | ✅      | ✅      |
+| `bvec2`                | ✅      | ✅      |
+| `bvec3`                | ✅      | ✅      |
+| `bvec4`                | ✅      | ✅      |
+| `mat2`                 | ✅      | ✅      |
+| `mat3`                 | ✅      | ✅      |
+| `mat4`                 | ✅      | ✅      |
+| `sampler2D`            | ✅      | ✅      |
+| `samplerCube`          | ✅      | ✅      |
+| `uint`                 | ❌      | ✅      |
+| `uvec2`                | ❌      | ✅      |
+| `uvec3`                | ❌      | ✅      |
+| `uvec4`                | ❌      | ✅      |
+| `mat2x3`               | ❌      | ✅      |
+| `mat2x4`               | ❌      | ✅      |
+| `mat3x2`               | ❌      | ✅      |
+| `mat3x4`               | ❌      | ✅      |
+| `mat4x2`               | ❌      | ✅      |
+| `mat4x3`               | ❌      | ✅      |
+| `sampler3D`            | ❌      | ✅      |
+| `sampler2DArray`       | ❌      | ✅      |
+| `sampler2DShadow`      | ❌      | ✅      |
+| `samplerCubeShadow`    | ❌      | ✅      |
+| `sampler2DArrayShadow` | ❌      | ✅      |
+| `isampler2D`           | ❌      | ✅      |
+| `isampler3D`           | ❌      | ✅      |
+| `isamplerCube`         | ❌      | ✅      |
+| `isampler2DArray`      | ❌      | ✅      |
+| `usampler2D`           | ❌      | ✅      |
+| `usampler3D`           | ❌      | ✅      |
+| `usamplerCube`         | ❌      | ✅      |
+| `usampler2DArray`      | ❌      | ✅      |
+
+### 📝 Attribute Types
+
+| Type     | WebGL 1 | WebGL 2 |
+| -------- | ------- | ------- |
+| `float`  | ✅      | ✅      |
+| `vec2`   | ✅      | ✅      |
+| `vec3`   | ✅      | ✅      |
+| `vec4`   | ✅      | ✅      |
+| `mat2`   | ✅      | ✅      |
+| `mat3`   | ✅      | ✅      |
+| `mat4`   | ✅      | ✅      |
+| `int`    | ❌      | ✅      |
+| `ivec2`  | ❌      | ✅      |
+| `ivec3`  | ❌      | ✅      |
+| `ivec4`  | ❌      | ✅      |
+| `uint`   | ❌      | ✅      |
+| `uvec2`  | ❌      | ✅      |
+| `uvec3`  | ❌      | ✅      |
+| `uvec4`  | ❌      | ✅      |
+| `mat2x3` | ❌      | ✅      |
+| `mat2x4` | ❌      | ✅      |
+| `mat3x2` | ❌      | ✅      |
+| `mat3x4` | ❌      | ✅      |
+| `mat4x2` | ❌      | ✅      |
+| `mat4x3` | ❌      | ✅      |