@bigmistqke/view.gl 0.1.3 → 0.1.5

package/README.md

@@ -10,56 +10,48 @@
 - [📦 Install](#-install)
 - [👁️ view.gl](#️-viewgl)
   - [🚀 Basic Usage](#-basic-usage)
-  - [👀 View Types](#-view-types)
+  - [👁️ view](#️-view)
+  - [👀 Resource Views](#-resource-views)
     - [🎯 uniformView](#-uniformview)
     - [📝 attributeView](#-attributeview)
     - [🔗 interleavedAttributeView](#-interleavedattributeview)
     - [🗂️ bufferView](#-bufferview)
-  - [🎨 Drawing Examples](#-drawing-examples)
-    - [🖼️ Regular Drawing](#-regular-drawing)
-    - [📱 Instanced Drawing](#-instanced-drawing)
 - [🏷️ view.gl/tag](#️-viewgltag)
   - [🚀 Basic Usage](#-basic-usage-1)
-  - [📝 Template Features](#-template-features)
-  - [⚙️ Tag Functions](#️-tag-functions)
+  - [📝 glsl](#-glsl)
+    - [🧩 GLSL Fragment](#-glsl-fragment)
+    - [🔒 Symbol Variables](#-symbol-variables)
+    - [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)
-    - [📝 glsl](#-glsl)
-    - [⚙️ compile(gl, vertex, fragment)](#️-compilegl-vertex-fragment)
-  - [🔣 Symbol Support](#-symbol-support)
+  - [⚙️ 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
-```
-
-```shell
+# or
 pnpm add @bigmistqke/view.gl
-```
-
-```shell
+# or
 yarn add @bigmistqke/view.gl
 ```
 
-```shell
-bun add @bigmistqke/view.gl
-```
-
 ## 👁️ view.gl
 
-The view system provides type-safe WebGL resource management for uniforms, attributes, and buffers.
+The view system provides type-safe WebGL resource management for uniforms, attributes, and buffers
 
 ### 🚀 Basic Usage
 
 ```typescript
-import { view } from '@bigmistqke/view.gl'
-
 const { uniforms, attributes } = view(gl, program, {
   uniforms: {
     time: { kind: 'float' },
@@ -83,26 +75,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)
 ```
 
+**Parameters:**
+
+- `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
+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
-import { uniformView } from '@bigmistqke/view.gl'
-
 const uniforms = uniformView(gl, program, {
   time: { kind: 'float' },
   lights: { kind: 'vec3', size: 8 }, // Array uniform: vec3[8]
@@ -111,52 +151,103 @@ 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
+- `kind`: GLSL type (see [Uniform Types](#-uniform-types) for full list and WebGL compatibility)
+- `size`: Array size (optional) - converts uniform to array type
+
+<details>
+<summary>TypeScript Types</summary>
+
+```typescript
+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 buffer creation, binding, and data management.
+Manages vertex attributes with automatic buffer creation and binding.
 
 ```typescript
-import { attributeView } from '@bigmistqke/view.gl'
-
 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 (see [Attribute Types](#-attribute-types) for full list and WebGL compatibility)
+- `instanced`: Boolean - enables instanced rendering
+- `buffer`: Custom WebGLBuffer (optional)
 
-- `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
+<details>
+<summary>TypeScript Types</summary>
+
+```typescript
+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 and VAO optimization.
+Manages interleaved vertex data with automatic stride/offset calculation.
 
 ```typescript
-import { interleavedAttributeView } from '@bigmistqke/view.gl'
-
 const interleavedAttributes = interleavedAttributeView(gl, program, {
   vertexData: {
     layout: [
@@ -165,109 +256,90 @@ 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:**
+**InterleavedAttributeSchema:**
+A mapping of interleaved buffer names to their layout configuration. Each layout defines multiple attributes packed into a single buffer.
+
+- `layout`: Array of attribute definitions with `key` and `kind` (see [Attribute Types](#-attribute-types))
+- `instanced`: Boolean - applies to all attributes in layout
 
-- `layout`: Array of attribute definitions with `name` and `kind`
-- `instanced`: Boolean - applies `vertexAttribDivisor` to all attributes in layout
+<details>
+<summary>TypeScript Types</summary>
+
+```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>
+```
+
+</details>
 
 #### 🗂️ bufferView
 
-Manages generic WebGL buffers for various uses.
+Manages generic WebGL buffers.
 
 ```typescript
-import { bufferView } from '@bigmistqke/view.gl'
-
 const buffers = bufferView(gl, {
   indices: { target: 'ELEMENT_ARRAY_BUFFER' },
   data: { target: 'ARRAY_BUFFER', usage: 'DYNAMIC_DRAW' },
 })
 
-buffers.indices.set(indexData)
-buffers.indices.bind()
-
-buffers.data.set(dynamicData)
-buffers.data.bind()
+buffers.indices.set(indexData).bind()
+buffers.data.set(dynamicData).bind()
 ```
 
-**Settings:**
+**BufferSchema:**
+A mapping of buffer names to their configuration. Each buffer has a target type and optional usage pattern.
 
 - `target`: Buffer target (`'ARRAY_BUFFER'`, `'ELEMENT_ARRAY_BUFFER'`)
 - `usage`: Usage pattern (`'STATIC_DRAW'`, `'DYNAMIC_DRAW'`, `'STREAM_DRAW'`)
 
-### 🎨 Drawing Examples
-
-#### 🖼️ Regular Drawing
+<details>
+<summary>TypeScript Types</summary>
 
 ```typescript
-const { attributes } = view(gl, program, {
-  attributes: {
-    position: { kind: 'vec3' },
-    uv: { kind: 'vec2' },
-  },
-})
+interface BufferOptions {
+  target: 'ARRAY_BUFFER' | 'ELEMENT_ARRAY_BUFFER'
+  usage?: 'STATIC_DRAW' | 'DYNAMIC_DRAW' | 'STREAM_DRAW' // Defaults to 'STATIC_DRAW'
+}
 
-attributes.position.set(vertices).bind()
-attributes.uv.set(uvData).bind()
-
-gl.drawArrays(gl.TRIANGLES, 0, vertexCount)
+type BufferSchema = Record<string | symbol, BufferOptions>
 ```
 
-#### 📱 Instanced Drawing
-
-```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)
-```
+</details>
 
 ## 🏷️ view.gl/tag
 
-The tag system provides GLSL template literal support with embedded schema definitions.
+Type-safe GLSL template literals with automatic schema extraction.
+
+- **Embedded Resources**: Define uniforms, attributes, and interleaved layouts directly in GLSL
+- **Type Inference**: Automatically infers schema types and creates type-safe view
+- **Unique Variables**: Prevent naming collisions using symbols for unique shader variables
+- **GLSL Composition**: Compose reusable GLSL fragments with automatic dependency resolution
 
 ### 🚀 Basic Usage
 
 ```typescript
-import { glsl, uniform, attribute, compile } from '@bigmistqke/view.gl/tag'
-
 const vertexShader = glsl`
   ${attribute.vec3('position')}
-  ${attribute.vec2('uv')}
-  ${uniform.mat4('projection')}
   ${uniform.mat4('model')}
   
   varying vec2 vUv;
   
   void main() {
     vUv = uv;
-    gl_Position = projection * model * vec4(position, 1.0);
+    gl_Position = model * vec4(position, 1.0);
   }
 `
 
@@ -284,170 +356,247 @@ const fragmentShader = glsl`
 const { program, schema } = compile(gl, vertexShader, fragmentShader)
 ```
 
-### 📝 Template Features
+### 📝 glsl
 
-- **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 [Symbol Support](#-symbol-support))
+Template literal processor that handles GLSL code and embedded resources. Supports interpolation of:
 
-### ⚙️ Tag Functions
-
-#### 🎯 uniform[kind](name, options?)
-
-Define uniform variables in GLSL templates. Supports all GLSL uniform types.
+- **[Resource tags](#️-resource-tags)**: `uniform.*()`, `attribute.*()`, `interleave()`
+- **[GLSL fragments](#-glsl-fragment)**: Reusable shader code snippets
+- **[Symbol Variables](#-symbol-variables)**: Unique variable names to prevent collisions
+- **Strings**: Interpolated as-is into the shader code
+- **Arrays**: Arrays of any supported interpolation types
 
 ```typescript
-import { uniform, glsl } from '@bigmistqke/view.gl/tag'
+const precision = 'precision mediump float;'
+const functionName = Symbol('function')
 
 const shader = glsl`
-  ${uniform.float('time')}
+  ${precision}                                // String interpolated as-is
   ${uniform.vec2('resolution')}
-  ${uniform.mat4('projection')}
-  ${uniform.sampler2D('texture')}
-  ${uniform.vec3('lights', { size: 8 })} // Array uniform: vec3[8]
+  ${[attribute.vec3('position'), attribute.vec2('uv')]}  // Array interpolation
+  
+  vec3 ${functionName}(vec2 uv) {             // Symbol interpolated to unique identifier
+    return vec3(uv, 0.5);
+  }
   
   void main() {
-    // Use uniforms in shader code
+    gl_Position = vec4(position, 1.0);
   }
 `
 ```
 
-**Available types**: `float`, `int`, `bool`, `vec2`, `vec3`, `vec4`, `ivec2`, `ivec3`, `ivec4`, `bvec2`, `bvec3`, `bvec4`, `mat2`, `mat3`, `mat4`, `sampler2D`, `samplerCube`
+#### 🧩 GLSL Fragment
 
-**Options**:
-
-- `size`: Array size (creates array uniform with Float32Array setter)
-
-#### 📝 attribute[kind](name, options?)
-
-Define vertex attributes in GLSL templates.
+Compose reusable GLSL code fragments to build complex shaders:
 
 ```typescript
-import { attribute, glsl } from '@bigmistqke/view.gl/tag'
+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.vec2('uv')}
+  ${attribute.vec3('direction')}
   ${attribute.vec3('normal')}
-  ${attribute.vec2('instanceOffset', { instanced: true })}
+  ${lighting}                                 // Include the lighting fragment
+  
+  varying vec3 vLighting;
   
   void main() {
-    gl_Position = vec4(position + vec3(instanceOffset, 0.0), 1.0);
+    vLighting = calculateLighting(normal, direction);
   }
 `
 ```
 
-**Available types**: `float`, `vec2`, `vec3`, `vec4`, `mat2`, `mat3`, `mat4`, `int`, `ivec2`, `ivec3`, `ivec4`
+#### 🔒 Symbol Variables
 
-**Options**:
+Use JavaScript symbols to prevent naming collisions:
 
-- `instanced`: Boolean - enables instanced rendering with `vertexAttribDivisor`
-- `buffer`: Custom WebGLBuffer (optional)
+```typescript
+const sum = Symbol('sum')
 
-#### 🔗 interleave(name, layout, options?)
+const sumFragment = glsl`
+float ${sum}(float a, float b){
+  return a + b;
+}`
 
-Define interleaved attribute layouts for efficient vertex data.
+const shader = glsl`
+${sumFragment}
 
-```typescript
-import { interleave, glsl } from '@bigmistqke/view.gl/tag'
+void main(){
+  float result = ${sum}(1.0, 2.0);
+}
+`
+```
 
-const vertexShader = glsl`
-  ${interleave('vertexData', [
-    { key: 'position', kind: 'vec3' },
-    { key: 'normal', kind: 'vec3' },
-    { key: 'uv', kind: 'vec2' },
-  ])}
-  
-  ${interleave(
-    'instanceData',
-    [
-      { key: 'instancePos', kind: 'vec2' },
-      { key: 'instanceColor', kind: 'vec3' },
-    ],
-    { instanced: true },
-  )}
-  
-  void main() {
-    gl_Position = vec4(position + vec3(instancePos, 0.0), 1.0);
-  }
+Symbols are converted to unique identifiers during the compilation of 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('position')}               // → attribute vec3 position;
+  varying vec2 vUv;
 `
 ```
 
-**Layout format**:
+If the shader starts with `#version 300 es`, resource tags generate WebGL2 syntax:
 
-- `key`: Attribute name
-- `kind`: GLSL type
+```typescript
+// WebGL2
+const shader = glsl`#version 300 es
+  ${attribute.vec3('position')}               // → in vec3 position;
+  out vec2 vUv;
+`
+```
 
-**Options**:
+### ⚙️ Resource Tags
 
-- `instanced`: Boolean - applies `vertexAttribDivisor` to all attributes
+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.
 
-#### 📝 glsl
+#### 🎯 uniform[kind](name, options?)
 
-Template literal processor that handles GLSL code and embedded resources.
+Define uniform variables in GLSL templates (see [Uniform Types](#-uniform-types)).
 
 ```typescript
-import { glsl } from '@bigmistqke/view.gl/tag'
+const uniqueTime = Symbol('time')
 
 const shader = glsl`
-  precision mediump float;
-  
-  ${uniform.vec2('resolution')}
+  ${uniform.float('time')}                    // String key
+  ${uniform.float(uniqueTime)}                // Symbol key
+  ${uniform.vec3('lights', { size: 8 })}      // Array uniform: vec3[8]
   
   void main() {
-    vec2 uv = gl_FragCoord.xy / resolution;
-    gl_FragColor = vec4(uv, 0.0, 1.0);
+    float wave = sin(time * 2.0 + ${uniqueTime});
+    vec3 totalLight = vec3(0.0);
+    for(int i = 0; i < 8; i++) {
+      totalLight += lights[i] * wave;
+    }
+    gl_FragColor = vec4(totalLight, 1.0);
   }
 `
 ```
 
-#### ⚙️ compile(gl, vertex, fragment)
+**Parameters**:
 
-Compiles shaders and extracts schema from embedded resources.
+- `name`: Uniform name (string or symbol for unique variables)
+- `options`: Optional configuration object
+  - `size`: Array size (creates array uniform with Float32Array setter)
 
-```typescript
-import { compile } from '@bigmistqke/view.gl/tag'
+#### 📝 attribute[kind](name, options?)
 
-const { program, schema } = compile(gl, vertexShader, fragmentShader)
+Define vertex attributes in GLSL templates (see [Attribute Types](#-attribute-types)).
+
+```typescript
+const uniquePosition = Symbol('position')
 
-// Schema contains extracted uniforms, attributes, and buffers
-console.log(schema.uniforms) // { time: { kind: 'float' }, ... }
-console.log(schema.attributes) // { position: { kind: 'vec3' }, ... }
+const vertexShader = glsl`
+  ${attribute.vec3('position')}               // String key
+  ${attribute.vec3(uniquePosition)}           // Symbol key
+  ${attribute.vec2('offset', { instanced: true })}
+  
+  void main() {
+    gl_Position = vec4(position + vec3(offset, 0.0), 1.0);
+  }
+`
 ```
 
-**Returns**:
+**Parameters**:
 
-- `program`: Compiled WebGL program
-- `schema`: Extracted resource definitions for use with `view()`
+- `name`: Attribute name (string or symbol for unique variables)
+- `options`: Optional configuration object
+  - `instanced`: Boolean - enables instanced rendering with `vertexAttribDivisor`
+  - `buffer`: Custom WebGLBuffer (optional)
 
-### 🔣 Symbol Support
+#### 🔗 interleave(name, layout, options?)
 
-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.
+Define interleaved attribute layouts for efficient vertex data.
 
 ```typescript
-const u_time = Symbol('time')
-const a_position = Symbol('position')
+const uniqueVertexData = Symbol('vertexData')
+const uniquePosition = Symbol('position')
 
-const shader = glsl`
-  ${attribute.vec3(a_position)}
-  ${uniform.float(u_time)}
+const vertexShader = glsl`
+  ${interleave('vertexData', [
+    // String key
+    { key: 'position', kind: 'vec3' },
+    { key: 'uv', kind: 'vec2' },
+  ])}
+  ${interleave(uniqueVertexData, [
+    // Symbol key
+    { key: uniquePosition, kind: 'vec3' },    // Symbol keys in layout
+    { key: 'uv', kind: 'vec2' },
+  ])}
   
   void main() {
-    gl_Position = vec4(${a_position}, ${u_time});
+    gl_Position = vec4(position + vec3(uv, 0.0), 1.0);
   }
 `
 ```
 
+**Parameters**:
+
+- `name`: Buffer name (string or symbol for unique variables)
+- `layout`: Array of attribute definitions
+  - `key`: Attribute name (string or symbol for unique variables)
+  - `kind`: GLSL type (see [Attribute Types](#-attribute-types))
+- `options`: Optional configuration object
+  - `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
+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:
+When manually constructing GLSL strings, use `toID()` to convert symbols to valid, unique identifiers:
 
 ```typescript
-import { createProgram, view, toID } from 'view.gl'
-
 const u_time = Symbol('time')
 const a_position = Symbol('position')
 
@@ -489,8 +638,6 @@ uniforms[u_time].set(performance.now())
 Creates and links a WebGL program from vertex and fragment shader sources.
 
 ```typescript
-import { createProgram } from '@bigmistqke/view.gl/utils'
-
 const program = createProgram(gl, vertexShaderSource, fragmentShaderSource)
 ```
 
@@ -499,8 +646,6 @@ const program = createProgram(gl, vertexShaderSource, fragmentShaderSource)
 Creates a WebGL texture with specified parameters.
 
 ```typescript
-import { createTexture } from '@bigmistqke/view.gl/utils'
-
 const texture = createTexture(
   gl,
   {
@@ -525,8 +670,6 @@ Automatically validates WebGL2-only formats and provides fallbacks for WebGL1.
 Creates a framebuffer with attached texture for render-to-texture operations.
 
 ```typescript
-import { createFramebuffer } from '@bigmistqke/view.gl/utils'
-
 const { framebuffer, texture } = createFramebuffer(gl, {
   width: 512,
   height: 512,
@@ -538,3 +681,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` | ❌      | ✅      |