rewrite(phase3): docs preparation for 1.1

docs/.vitepress/config.mts

@@ -9,7 +9,8 @@ function nav() {
     {
       text: 'API Reference',
       items: [
-        { text: '1.0', link: '/api/1.0/warp' }
+        { text: '1.0', link: '/api/1.0/warp' },
+        { text: '1.1', link: '/api/1.1/warp' }
       ]
     }
   ]
@@ -17,6 +18,27 @@ function nav() {
 
 function side() {
   return {
+    '/api/1.1': [
+      {
+        text: 'API Reference',
+        items: [
+          { text: 'Warp', link: '/api/1.1/warp' },
+          {
+            text: 'Event',
+            items: [
+              { text: 'Server', link: '/api/1.1/server' },
+              { text: 'Client', link: '/api/1.1/client' },
+            ]
+          },
+          {
+            text: 'Utilities',
+            items: [
+              { text: 'Buffer', link: '/api/1.1/buffer' },
+            ]
+          },
+        ]
+      }
+    ],
     '/api/1.0': [
       {
         text: 'API Reference',

docs/api/1.1/buffer.md

@@ -0,0 +1,147 @@
+# Buffer <Badge type="tip" text="module" />
+
+For efficient data serialization and schema definition with optimized packing.
+
+## Getting the Buffer Object
+
+```lua
+local Buffer = Warp.Buffer()
+```
+
+## Schema System <Badge type="tip" text="v1.1" />
+
+Define strict data schemas for optimized serialization and type safety.
+
+### Available Schema Types
+
+```lua
+{
+	-- Basic types
+	"boolean",
+	"string",
+	"nil",
+	
+	-- Numeric types
+	"uint8",
+	"uint16", 
+	"uint32",
+	"int8",
+	"int16",
+	"int32",
+	"float32",
+	"float64",
+	
+	-- Roblox types
+	"buffer"
+	"Vector2",
+	"Vector3",
+	"CFrame",
+	"Color3",
+	"BrickColor",
+	"Instance",
+	"EnumItem",
+	"Enum",
+	"UDim2",
+	"UDim",
+	"Rect",
+	"NumberRange",
+	"Ray",
+	"ColorSequence",
+	"NumberSequence",
+}
+```
+
+## Writer and Reader Functions
+
+### `.createWriter`
+
+Create a new buffer writer for serializing data.
+
+::: code-group
+```lua [Variable]
+(
+	capacity: number? -- Optional initial capacity (default: 64)
+): Writer
+```
+
+```lua [Example]
+local Buffer = Warp.Buffer()
+local writer = Buffer.createWriter(256) -- Pre-allocate 256 bytes
+```
+:::
+
+### `.build`
+
+Build the final buffer for transmission.
+
+::: code-group
+```lua [Variable]
+(
+	writer: Writer
+): buffer -- Returns buffer
+```
+
+```lua [Example]
+local Buffer = Warp.Buffer()
+local writer = Buffer.createWriter()
+
+-- Write some data
+Buffer.packValue(writer, "Hello World")
+Buffer.packValue(writer, 12345)
+
+-- Build final buffer
+local finalBuffer = Buffer.build(writer)
+print(buffer.len(finalBuffer))
+```
+:::
+
+### `.buildWithRefs`
+
+Build the final buffer with instance references for transmission.
+
+::: code-group
+```lua [Variable]
+(
+	writer: Writer
+): (buffer, { Instance }?) -- Returns buffer and optional instance references
+```
+
+```lua [Example]
+local Buffer = Warp.Buffer()
+local writer = Buffer.createWriter()
+
+-- Write some data with instances
+Buffer.packValue(writer, workspace.Part)
+Buffer.packValue(writer, game.Players.LocalPlayer)
+
+-- Build final buffer
+local finalBuffer, refs = Buffer.buildWithRefs(writer)
+print(buffer.len(finalBuffer), refs)
+```
+:::
+
+### `.reset`
+
+Reset a writer for reuse, clearing all data.
+
+::: code-group
+```lua [Variable]
+(
+	writer: Writer
+)
+```
+
+```lua [Example]
+local Buffer = Warp.Buffer()
+local writer = Buffer.createWriter()
+
+-- Use writer for first batch
+Buffer.writeEvents(writer, events1)
+local buffer1 = Buffer.build(writer)
+
+-- Reset and reuse for second batch
+Buffer.reset(writer)
+Buffer.writeEvents(writer, events2)
+local buffer2 = Buffer.build(writer)
+```
+:::

docs/api/1.1/client.md

@@ -0,0 +1,214 @@
+# Client <Badge type="tip" text="1.1" />
+
+For Client-sided operations.
+
+## Getting the Client Object
+
+```lua
+local Client = Warp.Client()
+```
+
+## `.Connect`
+
+Connect to an event to receive incoming data from the server.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	fn: (...any) -> ...any
+) -> Connection
+```
+
+```lua [Example]
+local connection = Client.Connect("ServerNotify", function(message, sender)
+	print(`Server message from {sender}: {message}`)
+end)
+print(connection.Connected)
+```
+:::
+
+## `.Once`
+
+Similar to `:Connect` but automatically disconnects after the first firing.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	fn: (...any) -> ...any
+) -> Connection
+```
+
+```lua [Example]
+Client.Once("WelcomeMessage", function(welcomeText)
+	print(`Welcome: {welcomeText}`)
+end)
+```
+:::
+
+## `.Wait` <Badge type="warning" text="yield" />
+
+Wait for an event to be triggered.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string
+) -> (number, ...any)
+```
+
+```lua [Example]
+local elapsed, message = Client.Wait("ServerMessage")
+print(`Received message after {elapsed} seconds: {message}`)
+```
+:::
+
+## `.Disconnect`
+
+Disconnect the event connection.
+
+::: code-group
+```lua [Variable]
+()
+```
+
+```lua [Example]
+local connection = Client.Connect("ServerNotify", function(message, sender)
+	print(`Server message from {sender}: {message}`)
+	-- Disconnect the connection
+	connection:Disconnect()
+end)
+print(Connection.Connected)
+```
+:::
+
+## `.DisconnectAll`
+
+Disconnect all connections for a specific event.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string
+)
+```
+
+```lua [Example]
+Client.DisconnectAll("ServerNotify")
+```
+:::
+
+## `.Destroy`
+
+Disconnect all connections and remove the event.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string
+)
+```
+
+```lua [Example]
+Client.Destroy("ServerNotify")
+```
+:::
+
+## `.Fire`
+
+Fire an event to the server.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	reliable: boolean,
+	...: any
+)
+```
+
+```lua [Example]
+-- (TCP) Reliable event (guaranteed delivery)
+Client.Fire("PlayerAction", true, "jump", playerPosition)
+
+-- (UDP) Unreliable event (faster but not guaranteed)
+Client.Fire("PositionUpdate", false, currentPosition)
+```
+:::
+
+## `.Invoke` <Badge type="warning" text="yield" />
+
+Invoke the server with timeout support.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	timeout: number?,
+	...: any
+) -> ...any
+```
+
+```lua [Example]
+local Client = Warp.Client()
+local response = Client.Invoke("RequestData", 3, "playerStats")
+if response then
+	print("Server responded:", response)
+else
+	print("Request timed out")
+end
+```
+:::
+
+::: warning
+This function is yielded. Returns `nil` if timeout occurs.
+:::
+
+## `.useSchema`
+
+Define a schema for strict data packing on a specific event.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	schema: Buffer.SchemaType
+)
+```
+
+```lua [Example]
+local Client = Warp.Client()
+
+-- Define a schema for position updates
+local positionSchema = Client.Schema.struct({
+	x = Client.Schema.f32,
+	y = Client.Schema.f32,
+	z = Client.Schema.f32,
+	timestamp = Client.Schema.u32
+})
+-- Define a schema for data updates
+local dataSchema = Client.Schema.struct({
+	Coins = Client.Schema.u32,
+	Level = Client.Schema.u8,
+	Inventory = Client.Schema.array(Client.Schema.u32),
+	Settings = Client.Schema.struct({
+		VFX = Client.Schema.boolean,
+		Volume = Client.Schema.f32,
+		Language = Client.Schema.string,
+	})
+})
+
+-- Now this event will use the schema
+Client.useSchema("DataReplication", dataSchema)
+Client.useSchema("PositionUpdate", positionSchema)
+Client.Connect("PositionUpdate", function(x, y, z, timestamp)
+	-- Data is automatically deserialized according to schema
+	updatePlayerPosition(x, y, z)
+end)
+```
+:::
+
+## `.Schema`
+
+Access to Buffer.Schema for creating data schemas.

docs/api/1.1/server.md

@@ -0,0 +1,216 @@
+# Server <Badge type="tip" text="1.1" />
+
+For Server-sided operations.
+
+## Getting the Server Object
+
+```lua
+local Server = Warp.Server()
+```
+
+## `.Connect`
+
+Connect to an event to receive incoming data from clients.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	fn: (player: Player, ...any) -> ...any
+) -> Connection
+```
+
+```lua [Example]
+local connection = Server.Connect("ServerNotify", function(player, message)
+	print(`Client message from {player}: {message}`)
+end)
+print(connection.Connected)
+```
+:::
+
+## `.Once`
+
+Similar to `:Connect` but automatically disconnects after the first firing.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	fn: (player: Player, ...any) -> ...any
+) -> Connection
+```
+
+```lua [Example]
+Server.Once("WelcomeMessage", function(welcomeText)
+	print(`Welcome: {welcomeText}`)
+end)
+```
+:::
+
+## `.Wait` <Badge type="warning" text="yield" />
+
+Wait for an event to be triggered.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string
+) -> (number, ...any)
+```
+
+```lua [Example]
+local elapsed, message = Server.Wait("ServerMessage")
+print(`Received message after {elapsed} seconds: {message}`)
+```
+:::
+
+## `.DisconnectAll`
+
+Disconnect all connections for a specific event.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string
+)
+```
+
+```lua [Example]
+Server.DisconnectAll("ServerNotify")
+```
+:::
+
+## `.Destroy`
+
+Disconnect all connections and remove the event.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string
+)
+```
+
+```lua [Example]
+Server.Destroy("ServerNotify")
+```
+:::
+
+## `.Fire`
+
+Fire an event to a specific player.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	reliable: boolean,
+	player: Player,
+	...: any
+)
+```
+
+```lua [Example]
+Server.Fire("ServerNotify", true, player, "Hello from server!")
+```
+:::
+
+## `.Fires`
+
+Fire an event to all connected players.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	reliable: boolean,
+	...: any
+)
+```
+
+```lua [Example]
+Server.Fires("Broadcast", true, "Server announcement!")
+```
+:::
+
+## `.FireExcept`
+
+Fire an event to all players except specified ones.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	reliable: boolean,
+	except: { Player },
+	...: any
+)
+```
+
+```lua [Example]
+local excludedPlayers = { player1, player2 }
+Server.FireExcept("Update", true, excludedPlayers, "Game update")
+```
+:::
+
+## `.Invoke` <Badge type="warning" text="yield" />
+
+Invoke a client with timeout support.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	player: Player,
+	timeout: number?,
+	...: any
+) -> ...any
+```
+
+```lua [Example]
+local response = Server.Invoke("RequestData", player, 3, "userInfo")
+if response then
+	print("Client responded:", response)
+else
+	print("Request timed out")
+end
+```
+:::
+
+::: warning
+This function is yielded. Returns `nil` if timeout occurs.
+:::
+
+## `.useSchema`
+
+Define a schema for strict data packing on a specific event.
+
+::: code-group
+```lua [Variable]
+(
+	remoteName: string,
+	schema: Buffer.SchemaType
+)
+```
+
+```lua [Example]
+local Server = Warp.Server()
+
+local dataSchema = Server.Schema.struct({
+	Coins = Server.Schema.u32,
+	Level = Server.Schema.u8,
+	Inventory = Server.Schema.array(Server.Schema.u32),
+	Settings = Server.Schema.struct({
+		VFX = Server.Schema.boolean,
+		Volume = Server.Schema.f32,
+		Language = Server.Schema.string,
+	})
+})
+
+Server.useSchema("DataReplication", dataSchema)
+```
+:::
+
+## `.Schema`
+
+Access to Buffer.Schema for creating data schemas.

docs/api/1.1/warp.md

@@ -0,0 +1,34 @@
+# Warp <Badge type="tip" text="1.1" />
+
+The public main of the Warp library.
+::: warning
+This version (1.1.x) are not backward compatible with 1.0.x.
+:::
+
+## `.Server` <Badge type="tip" text="server side" />
+
+Get the Server operation for server-side.
+
+```lua
+-- Server
+local Server = Warp.Server()
+```
+
+## `.Client` <Badge type="tip" text="client side" />
+
+Get the Client operation for client-side.
+
+```lua
+-- Client
+local Client = Warp.Client()
+```
+
+## `.Buffer` <Badge type="tip" text="universal" />
+
+Get the Buffer util for schema definition.
+
+```lua
+-- Universal (Server & Client)
+local Buffer = Warp.Buffer()
+local schema = Buffer.Schema
+```

docs/guide/example.md

@@ -1,4 +1,4 @@
-# Example
+# Example <Badge type="tip" text="1.0" />
 
 Let's try and play something with Warp!
 

docs/guide/getting-started.md

@@ -1,4 +1,4 @@
-# Getting Started
+# Getting Started <Badge type="tip" text="1.0" />
 
 ### `Step 1:`
 First, you have to require the Warp module.