@axpecter/lync 2.2.1 → 2.3.1

package/src/codec/meta/Auto.luau

@@ -8,6 +8,7 @@ local CFrameC = require(script.Parent.Parent.datatype.CFrame)
 local Channel = require(script.Parent.Parent.Parent.internal.Channel)
 local ColorC = require(script.Parent.Parent.datatype.Color)
 local IVC = require(script.Parent.Parent.datatype.IntVector)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local NRC = require(script.Parent.Parent.datatype.NumberRange)
 local NumberC = require(script.Parent.Parent.primitive.Number)
 local RayC = require(script.Parent.Parent.datatype.Ray)
@@ -53,6 +54,78 @@ local TAG_COLSEQ = 26
 local INLINE_MAX = Varint.INLINE_MAX
 local F32_SCRATCH = NumberC._f32Scratch
 
+-- Tag -> numeric primitive dispatch tables.
+local NUM_SIZE: { [number]: number } = table.freeze({
+    [TAG_U8] = 1,
+    [TAG_I8] = 1,
+    [TAG_U16] = 2,
+    [TAG_I16] = 2,
+    [TAG_U32] = 4,
+    [TAG_I32] = 4,
+    [TAG_F32] = 4,
+    [TAG_F64] = 8,
+})
+
+local NUM_WRITE: { [number]: (buffer, number, number) -> () } = table.freeze({
+    [TAG_U8] = buffer.writeu8,
+    [TAG_U16] = buffer.writeu16,
+    [TAG_U32] = buffer.writeu32,
+    [TAG_I8] = Signed.writeI8,
+    [TAG_I16] = Signed.writeI16,
+    [TAG_I32] = Signed.writeI32,
+    [TAG_F32] = buffer.writef32,
+    [TAG_F64] = buffer.writef64,
+})
+
+local NUM_READ: { [number]: (buffer, number) -> number } = table.freeze({
+    [TAG_U8] = buffer.readu8,
+    [TAG_U16] = buffer.readu16,
+    [TAG_U32] = buffer.readu32,
+    [TAG_I8] = buffer.readi8,
+    [TAG_I16] = buffer.readi16,
+    [TAG_I32] = buffer.readi32,
+    [TAG_F32] = buffer.readf32,
+    [TAG_F64] = buffer.readf64,
+})
+
+type TypeEntry = { tag: number, codec: Types.InternalCodec<any> }
+
+local TYPE_DISPATCH: { [string]: TypeEntry } = table.freeze({
+    Vector2 = { tag = TAG_VEC2, codec = VecC.vec2 },
+    Vector3 = { tag = TAG_VEC3, codec = VecC.vec3 },
+    Color3 = { tag = TAG_COLOR3, codec = ColorC.color3 },
+    CFrame = { tag = TAG_CFRAME, codec = CFrameC.cframe },
+    UDim = { tag = TAG_UDIM, codec = UDimC.udim },
+    UDim2 = { tag = TAG_UDIM2, codec = UDimC.udim2 },
+    NumberRange = { tag = TAG_NUMRANGE, codec = NRC.numberRange },
+    Rect = { tag = TAG_RECT, codec = RectC.rect },
+    Vector2int16 = { tag = TAG_V2I16, codec = IVC.vec2int16 },
+    Vector3int16 = { tag = TAG_V3I16, codec = IVC.vec3int16 },
+    Region3 = { tag = TAG_REGION3, codec = RegionC.region3 },
+    Region3int16 = { tag = TAG_R3I16, codec = RegionC.region3int16 },
+    Ray = { tag = TAG_RAY, codec = RayC.ray },
+    NumberSequence = { tag = TAG_NUMSEQ, codec = SeqC.numberSequence },
+    ColorSequence = { tag = TAG_COLSEQ, codec = SeqC.colorSequence },
+})
+
+local READ_DISPATCH: { [number]: Types.InternalCodec<any> } = table.freeze({
+    [TAG_VEC2] = VecC.vec2,
+    [TAG_VEC3] = VecC.vec3,
+    [TAG_COLOR3] = ColorC.color3,
+    [TAG_CFRAME] = CFrameC.cframe,
+    [TAG_UDIM] = UDimC.udim,
+    [TAG_UDIM2] = UDimC.udim2,
+    [TAG_NUMRANGE] = NRC.numberRange,
+    [TAG_RECT] = RectC.rect,
+    [TAG_V2I16] = IVC.vec2int16,
+    [TAG_V3I16] = IVC.vec3int16,
+    [TAG_REGION3] = RegionC.region3,
+    [TAG_R3I16] = RegionC.region3int16,
+    [TAG_RAY] = RayC.ray,
+    [TAG_NUMSEQ] = SeqC.numberSequence,
+    [TAG_COLSEQ] = SeqC.colorSequence,
+})
+
 -- Private ----------------------------------------------------------------
 
 local alloc = Base.alloc
@@ -62,10 +135,12 @@ local readu8 = buffer.readu8
 local floor = math.floor
 local isnan = math.isnan
 
-local writeI8 = Signed.writeI8
-local writeI16 = Signed.writeI16
-local writeI32 = Signed.writeI32
-
+--[[
+    Pick the narrowest tag for a number. NaN forces F64 (no integer or F32
+    can represent it). Integers walk u8 -> u16 -> u32 / i8 -> i16 -> i32; non-
+    integers try f32 by round-tripping through scratch (see Number.luau) and
+    fall through to f64 if precision is lost.
+]]
 local function selectNumberTag(value: number): number
     if isnan(value) then
         return TAG_F64
@@ -95,7 +170,6 @@ local function selectNumberTag(value: number): number
         end
     end
 
-    -- Roblox is single-threaded so a module scratch cannot be aliased.
     buffer.writef32(F32_SCRATCH, 0, value)
     if buffer.readf32(F32_SCRATCH, 0) == value then
         return TAG_F32
@@ -103,114 +177,6 @@ local function selectNumberTag(value: number): number
     return TAG_F64
 end
 
-local function numberSize(tag: number): number
-    if tag == TAG_U8 or tag == TAG_I8 then
-        return 1
-    end
-    if tag == TAG_U16 or tag == TAG_I16 then
-        return 2
-    end
-    if tag == TAG_U32 or tag == TAG_I32 or tag == TAG_F32 then
-        return 4
-    end
-    return 8
-end
-
-local function writeNumber(b: buffer, off: number, tag: number, value: number): ()
-    if tag == TAG_U8 then
-        buffer.writeu8(b, off, value)
-        return
-    end
-    if tag == TAG_U16 then
-        buffer.writeu16(b, off, value)
-        return
-    end
-    if tag == TAG_U32 then
-        buffer.writeu32(b, off, value)
-        return
-    end
-    if tag == TAG_I8 then
-        writeI8(b, off, value)
-        return
-    end
-    if tag == TAG_I16 then
-        writeI16(b, off, value)
-        return
-    end
-    if tag == TAG_I32 then
-        writeI32(b, off, value)
-        return
-    end
-    if tag == TAG_F32 then
-        buffer.writef32(b, off, value)
-        return
-    end
-    buffer.writef64(b, off, value)
-end
-
-local function readNumber(b: buffer, off: number, tag: number): number
-    if tag == TAG_U8 then
-        return buffer.readu8(b, off)
-    end
-    if tag == TAG_U16 then
-        return buffer.readu16(b, off)
-    end
-    if tag == TAG_U32 then
-        return buffer.readu32(b, off)
-    end
-    if tag == TAG_I8 then
-        return buffer.readi8(b, off)
-    end
-    if tag == TAG_I16 then
-        return buffer.readi16(b, off)
-    end
-    if tag == TAG_I32 then
-        return buffer.readi32(b, off)
-    end
-    if tag == TAG_F32 then
-        return buffer.readf32(b, off)
-    end
-    return buffer.readf64(b, off)
-end
-
-type TypeEntry = { tag: number, codec: Types.InternalCodec<any> }
-
-local TYPE_DISPATCH: { [string]: TypeEntry } = table.freeze({
-    Vector2 = { tag = TAG_VEC2, codec = VecC.vec2 },
-    Vector3 = { tag = TAG_VEC3, codec = VecC.vec3 },
-    Color3 = { tag = TAG_COLOR3, codec = ColorC.color3 },
-    CFrame = { tag = TAG_CFRAME, codec = CFrameC.cframe },
-    UDim = { tag = TAG_UDIM, codec = UDimC.udim },
-    UDim2 = { tag = TAG_UDIM2, codec = UDimC.udim2 },
-    NumberRange = { tag = TAG_NUMRANGE, codec = NRC.numberRange },
-    Rect = { tag = TAG_RECT, codec = RectC.rect },
-    Vector2int16 = { tag = TAG_V2I16, codec = IVC.vec2int16 },
-    Vector3int16 = { tag = TAG_V3I16, codec = IVC.vec3int16 },
-    Region3 = { tag = TAG_REGION3, codec = RegionC.region3 },
-    Region3int16 = { tag = TAG_R3I16, codec = RegionC.region3int16 },
-    Ray = { tag = TAG_RAY, codec = RayC.ray },
-    NumberSequence = { tag = TAG_NUMSEQ, codec = SeqC.numberSequence },
-    ColorSequence = { tag = TAG_COLSEQ, codec = SeqC.colorSequence },
-})
-
-local READ_DISPATCH: { [number]: Types.InternalCodec<any> } = table.freeze({
-    [TAG_VEC2] = VecC.vec2,
-    [TAG_VEC3] = VecC.vec3,
-    [TAG_COLOR3] = ColorC.color3,
-    [TAG_CFRAME] = CFrameC.cframe,
-    [TAG_UDIM] = UDimC.udim,
-    [TAG_UDIM2] = UDimC.udim2,
-    [TAG_NUMRANGE] = NRC.numberRange,
-    [TAG_RECT] = RectC.rect,
-    [TAG_V2I16] = IVC.vec2int16,
-    [TAG_V3I16] = IVC.vec3int16,
-    [TAG_REGION3] = RegionC.region3,
-    [TAG_R3I16] = RegionC.region3int16,
-    [TAG_RAY] = RayC.ray,
-    [TAG_NUMSEQ] = SeqC.numberSequence,
-    [TAG_COLSEQ] = SeqC.colorSequence,
-})
-
 local function writeAuto(ch: Types.ChannelState, value: any): ()
     if value == nil then
         writeByte(ch, TAG_NIL)
@@ -233,15 +199,16 @@ local function writeAuto(ch: Types.ChannelState, value: any): ()
 
     if t == "number" then
         local tag = selectNumberTag(value)
-        local totalSize = 1 + numberSize(tag)
+        local size = NUM_SIZE[tag]
+        local total = 1 + size
         local cursor = ch.cursor
-        if cursor + totalSize > ch.size then
-            alloc(ch, totalSize)
+        if cursor + total > ch.size then
+            alloc(ch, total)
         end
         local b = ch.buff
         writeu8(b, cursor, tag)
-        writeNumber(b, cursor + 1, tag, value)
-        ch.cursor = cursor + totalSize
+        NUM_WRITE[tag](b, cursor + 1, value)
+        ch.cursor = cursor + total
         return
     end
 
@@ -250,6 +217,7 @@ local function writeAuto(ch: Types.ChannelState, value: any): ()
 
         local len = #value
         local cursor = ch.cursor
+        -- Inline single-byte length fast path; matches String.luau.
         if len <= INLINE_MAX then
             if cursor + 1 + len > ch.size then
                 alloc(ch, 1 + len)
@@ -280,22 +248,22 @@ local function writeAuto(ch: Types.ChannelState, value: any): ()
 
     local entry = TYPE_DISPATCH[t]
     if not entry then
-        error(`[Lync] Auto.write: unsupported type "{t}"`)
+        Log.error(`unsupported type "{t}"`)
     end
-
     local codec = entry.codec
     local size = codec._size
     local dw = codec._directWrite
+    -- Fixed-size + direct writer: single alloc + tag + payload.
     if size and dw then
-        local totalSize = 1 + size
+        local total = 1 + size
         local cursor = ch.cursor
-        if cursor + totalSize > ch.size then
-            alloc(ch, totalSize)
+        if cursor + total > ch.size then
+            alloc(ch, total)
         end
         local b = ch.buff
         writeu8(b, cursor, entry.tag)
         dw(b, cursor + 1, value)
-        ch.cursor = cursor + totalSize
+        ch.cursor = cursor + total
         return
     end
 
@@ -314,7 +282,7 @@ local function readAuto(src: buffer, pos: number, refs: { Instance }?): (any, nu
     end
 
     if tag >= TAG_U8 and tag <= TAG_F64 then
-        return readNumber(src, pos + 1, tag), 1 + numberSize(tag)
+        return NUM_READ[tag](src, pos + 1), 1 + NUM_SIZE[tag]
     end
 
     if tag == TAG_STRING then
@@ -332,7 +300,7 @@ local function readAuto(src: buffer, pos: number, refs: { Instance }?): (any, nu
 
     local codec = READ_DISPATCH[tag]
     if not codec then
-        error(`[Lync] Auto.read: unknown tag {tag}`)
+        Log.error(`unknown tag {tag}`)
     end
     local value, consumed = codec.read(src, pos + 1, refs)
     return value, 1 + consumed

package/src/codec/meta/Bitfield.luau

@@ -1,8 +1,9 @@
 --!strict
 --!native
--- Sub-byte packing. 1 to 32 bits across bool / uint / int fields.
+-- Sub-byte packed bool/uint/int fields. Up to 32 bits total per record.
 
 local Base = require(script.Parent.Parent.Base)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Constants --------------------------------------------------------------
@@ -18,12 +19,7 @@ local bor = bit32.bor
 local lshift = bit32.lshift
 local rshift = bit32.rshift
 
---[[
-    Width-aware mask: bit32.lshift(1, 32) returns 0, so 32-bit fields
-    need the all-ones mask explicitly. Sign-extension constants for int
-    fields use 2^(width-1) and 2^width via numeric exponentiation so
-    width=32 still produces 0x80000000 / 0x100000000 correctly.
-]]
+-- bit32.lshift(1, 32) wraps to 0; force all-ones in the 32-bit case.
 local function widthMask(width: number): number
     if width >= 32 then
         return 0xFFFFFFFF
@@ -38,6 +34,7 @@ local Bitfield = {}
 export type FieldSpec = { type: "bool" | "uint" | "int", width: number? }
 
 function Bitfield.define(schema: { [string]: FieldSpec }): Types.InternalCodec<any>
+    -- Sort field names so bit positions are stable across runs.
     local keys: { string } = {}
     for key in schema do
         table.insert(keys, key)
@@ -45,9 +42,7 @@ function Bitfield.define(schema: { [string]: FieldSpec }): Types.InternalCodec<a
     table.sort(keys)
 
     local fieldCount = #keys
-    if fieldCount == 0 then
-        error("[Lync] Lync.bitfield: requires at least one field")
-    end
+    Log.assert(fieldCount > 0, "requires at least one field")
 
     local fieldKeys = table.create(fieldCount)
     local fieldTypes = table.create(fieldCount)
@@ -72,7 +67,7 @@ function Bitfield.define(schema: { [string]: FieldSpec }): Types.InternalCodec<a
         elseif spec.type == "uint" then
             local width = spec.width
             if not width or width < 1 or width > 32 then
-                error(`[Lync] Lync.bitfield: field "{key}" uint width must be 1-32`)
+                Log.error(`field "{key}" uint width must be 1-32`)
             end
             fieldTypes[i] = TYPE_UINT
             fieldMasks[i] = widthMask(width)
@@ -81,8 +76,9 @@ function Bitfield.define(schema: { [string]: FieldSpec }): Types.InternalCodec<a
             totalBits += width
         elseif spec.type == "int" then
             local width = spec.width
+            -- Min int width is 2: 1 bit can't represent both a sign and a value.
             if not width or width < 2 or width > 32 then
-                error(`[Lync] Lync.bitfield: field "{key}" int width must be 2-32`)
+                Log.error(`field "{key}" int width must be 2-32`)
             end
             fieldTypes[i] = TYPE_INT
             fieldMasks[i] = widthMask(width)
@@ -90,14 +86,15 @@ function Bitfield.define(schema: { [string]: FieldSpec }): Types.InternalCodec<a
             fieldSignExt[i] = 2 ^ width
             totalBits += width
         else
-            error(`[Lync] Lync.bitfield: field "{key}" has unknown type "{spec.type}"`)
+            Log.error(`field "{key}" has unknown type "{spec.type}"`)
         end
     end
 
     if totalBits > 32 then
-        error(`[Lync] Lync.bitfield: total exceeds 32 bits ({totalBits})`)
+        Log.error(`total exceeds 32 bits ({totalBits})`)
     end
 
+    -- Pick the narrowest u8/u16/u32 wire form.
     local wireBytes: number
     local wfn: (buffer, number, number) -> ()
     local rfn: (buffer, number) -> number
@@ -137,6 +134,7 @@ function Bitfield.define(schema: { [string]: FieldSpec }): Types.InternalCodec<a
             if fieldTypes[i] == TYPE_BOOL then
                 result[fieldKeys[i]] = raw ~= 0
             elseif fieldTypes[i] == TYPE_INT then
+                -- Sign-extend: subtract 2^width when the sign bit is set.
                 result[fieldKeys[i]] = if raw >= fieldSignBit[i] then raw - fieldSignExt[i] else raw
             else
                 result[fieldKeys[i]] = raw

package/src/codec/meta/Custom.luau

@@ -3,6 +3,7 @@
 -- User-defined fixed-size codec.
 
 local Base = require(script.Parent.Parent.Base)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Private ----------------------------------------------------------------
@@ -20,8 +21,9 @@ function Custom.define<T>(
     typeCheck: string?
 ): Types.InternalCodec<T>
     if type(size) ~= "number" or size < 0 or floor(size) ~= size then
-        error("[Lync] Lync.custom: size must be a non-negative integer")
+        Log.error(`size must be a non-negative integer, got {size}`)
     end
+    -- size == 0 collapses to constant(nil): user has no payload to encode.
     if size == 0 then
         return Base.constant(nil :: any) :: Types.InternalCodec<T>
     end

package/src/codec/meta/Enum.luau

@@ -1,8 +1,9 @@
 --!strict
---!optimize 2
+--!native
 -- String-keyed enum codec. Maps values to u8 indices at definition time.
 
 local Base = require(script.Parent.Parent.Base)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Public -----------------------------------------------------------------
@@ -12,11 +13,9 @@ local EnumCodec = {}
 function EnumCodec.define(...: string): Types.InternalCodec<string>
     local values = { ... }
     local count = #values
-    if count == 0 then
-        error("[Lync] Lync.enum: requires at least one value")
-    end
+    Log.assert(count > 0, "requires at least one variant")
     if count > 256 then
-        error("[Lync] Lync.enum: exceeds 256 variants")
+        Log.error(`exceeds 256 variants ({count})`)
     end
 
     local toIndex: { [string]: number } = {}
@@ -24,7 +23,7 @@ function EnumCodec.define(...: string): Types.InternalCodec<string>
     for i = 1, count do
         local val = values[i]
         if toIndex[val] then
-            error(`[Lync] Lync.enum: duplicate value "{val}"`)
+            Log.error(`duplicate value "{val}"`)
         end
         toIndex[val] = i - 1
         toValue[i] = val
@@ -35,13 +34,14 @@ function EnumCodec.define(...: string): Types.InternalCodec<string>
     return Base.define(1, function(b: buffer, off: number, value: string): ()
         local idx = toIndex[value]
         if idx == nil then
-            error(`[Lync] Enum.write: invalid value "{value}"`)
+            Log.error(`invalid value "{value}"`)
         end
         buffer.writeu8(b, off, idx)
     end, function(b: buffer, off: number): string
-        local val = toValue[buffer.readu8(b, off) + 1]
+        local raw = buffer.readu8(b, off)
+        local val = toValue[raw + 1]
         if val == nil then
-            error(`[Lync] Enum.read: invalid index`)
+            Log.error(`invalid index {raw}`)
         end
         return val
     end, { _typeCheck = "string", _isEnum = true, _enumValues = toIndex })

package/src/codec/meta/Float.luau

@@ -1,17 +1,15 @@
 --!strict
 --!native
--- Fixed-point quantization codec. Maps a float range to u8/u16/u32.
+-- Fixed-point float quantizer. Maps a float range to u8/u16/u32.
 
 local Base = require(script.Parent.Parent.Base)
+local Quantize = require(script.Parent.Parent.Parent.util.Quantize)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Private ----------------------------------------------------------------
 
-local ceil = math.ceil
 local clamp = math.clamp
 local round = math.round
-local maxN = math.max
-local minN = math.min
 
 -- Public -----------------------------------------------------------------
 
@@ -22,33 +20,13 @@ function Float.float(
     rangeMax: number,
     precision: number
 ): Types.InternalCodec<number>
-    if rangeMin > rangeMax then
-        error(`[Lync] Lync.float: min ({rangeMin}) must be <= max ({rangeMax})`)
-    end
-    if precision <= 0 then
-        error("[Lync] Lync.float: precision must be positive")
-    end
-
-    local delta = rangeMax - rangeMin
-    if delta == 0 then
+    -- Degenerate range: emit nothing, decode to the constant.
+    if rangeMax - rangeMin == 0 then
         return Base.constant(rangeMin)
     end
 
-    local maxInt = minN(0xFFFFFFFF, maxN(1, ceil(delta / precision)))
-
-    local compBytes: number
-    local wfn: (buffer, number, number) -> ()
-    local rfn: (buffer, number) -> number
-    if maxInt <= 0xFF then
-        compBytes, wfn, rfn = 1, buffer.writeu8, buffer.readu8
-    elseif maxInt <= 0xFFFF then
-        compBytes, wfn, rfn = 2, buffer.writeu16, buffer.readu16
-    else
-        compBytes, wfn, rfn = 4, buffer.writeu32, buffer.readu32
-    end
-
-    local scale = maxInt / delta
-    local invScale = delta / maxInt
+    local compBytes, wfn, rfn, scale, invScale, delta =
+        Quantize.setup("Lync.float", rangeMin, rangeMax, precision)
 
     return Base.define(compBytes, function(b: buffer, off: number, value: number): ()
         wfn(b, off, round(clamp(value - rangeMin, 0, delta) * scale))

package/src/codec/meta/Nothing.luau

@@ -1,6 +1,6 @@
 --!strict
 --!optimize 2
--- Zero-byte codec. Reads nil. For fire-and-forget signals.
+-- 0-byte codec. Reads nil. For fire-and-forget signals.
 
 local Base = require(script.Parent.Parent.Base)
 

package/src/codec/meta/Unknown.luau

@@ -1,8 +1,9 @@
 --!strict
---!optimize 2
--- Bypasses buffer serialization. Uses Roblox remote sidecar refs.
+--!native
+-- Bypass codec. Stashes the value in the channel sidecar refs (no schema).
 
 local Channel = require(script.Parent.Parent.Parent.internal.Channel)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Private ----------------------------------------------------------------
@@ -15,20 +16,22 @@ local function writeUnknown(ch: Types.ChannelState, value: any): ()
 end
 
 local function readUnknown(src: buffer, pos: number, refs: { Instance }?): (any, number)
-    if not refs then
-        error("[Lync] Unknown.read: refs array is required")
+    local r = refs
+    if not r then
+        Log.error("refs array is required")
     end
     local idx = readu16(src, pos)
-    if idx < 1 or idx > #refs then
-        error(`[Lync] Unknown.read: ref index {idx} out of bounds`)
+    if idx < 1 or idx > #r then
+        Log.error(`ref index {idx} out of bounds`)
     end
-    return refs[idx], 2
+    return r[idx], 2
 end
 
 -- Public -----------------------------------------------------------------
 
 local Unknown = {}
 
+-- _hasUnknown propagates upward so containers warn when used without validate.
 Unknown.unknown = table.freeze({
     _hasUnknown = true,
     write = writeUnknown,

package/src/codec/primitive/Bool.luau

@@ -1,12 +1,10 @@
 --!strict
 --!optimize 2
--- Single-byte boolean codec. _isBool flag enables struct/array bit packing.
+-- 1-byte boolean codec. _isBool flag opts struct/array into bit packing.
 
 local Base = require(script.Parent.Parent.Base)
 
--- Public -----------------------------------------------------------------
-
-local Bool = {}
+-- Private ----------------------------------------------------------------
 
 local function writeBool(b: buffer, off: number, value: boolean): ()
     buffer.writeu8(b, off, if value then 1 else 0)
@@ -16,6 +14,10 @@ local function readBool(b: buffer, off: number): boolean
     return buffer.readu8(b, off) ~= 0
 end
 
+-- Public -----------------------------------------------------------------
+
+local Bool = {}
+
 Bool.bool = Base.define(1, writeBool, readBool, {
     _isBool = true,
     _typeCheck = "boolean",

package/src/codec/primitive/Float16.luau

@@ -1,6 +1,6 @@
 --!strict
 --!native
--- IEEE 754 binary16 codec. 2 bytes, +/- 65504, ~3 decimal digits of precision.
+-- IEEE 754 binary16 codec. 2 bytes, +/-65504 finite range, ~3 decimal digits.
 
 local Base = require(script.Parent.Parent.Base)
 
@@ -20,9 +20,10 @@ local frexp = math.frexp
 local ldexp = math.ldexp
 local round = math.round
 local huge = math.huge
+local isnan = math.isnan
 
 local function encode(value: number): number
-    if value ~= value then
+    if isnan(value) then
         return NAN_BITS
     end
     if value == 0 then
@@ -42,6 +43,7 @@ local function encode(value: number): number
     local mantissa, exponent = frexp(value)
     local biasedExp = exponent + 14
 
+    -- Subnormal: shift mantissa into the 10-bit fraction with the implicit bit gone.
     if biasedExp <= 0 then
         local frac = round(ldexp(mantissa, biasedExp + 10))
         if frac >= 1024 then
@@ -54,6 +56,7 @@ local function encode(value: number): number
     end
 
     local frac = round((mantissa * 2 - 1) * 1024)
+    -- Rounding can carry into the exponent; absorb it.
     if frac >= 1024 then
         frac = 0
         biasedExp += 1

package/src/codec/primitive/Int.luau

@@ -1,8 +1,9 @@
 --!strict
 --!optimize 2
--- Range-typed integer codec. Picks the narrowest u8/u16/u32/i8/i16/i32 wire form.
+-- Range-typed integer codec. Picks the narrowest u8/u16/u32/i8/i16/i32 form.
 
 local Base = require(script.Parent.Parent.Base)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local Signed = require(script.Parent.Signed)
 local Types = require(script.Parent.Parent.Parent.Types)
 
@@ -19,11 +20,9 @@ local Int = {}
 
 function Int.int(min: number, max: number): Types.InternalCodec<number>
     if min > max then
-        error(`[Lync] Lync.int: min ({min}) must be <= max ({max})`)
-    end
-    if floor(min) ~= min or floor(max) ~= max then
-        error("[Lync] Lync.int: bounds must be integers")
+        Log.error(`min ({min}) must be <= max ({max})`)
     end
+    Log.assert(floor(min) == min and floor(max) == max, "bounds must be integers")
 
     local meta = {
         _min = min,
@@ -54,7 +53,7 @@ function Int.int(min: number, max: number): Types.InternalCodec<number>
         end
     end
 
-    error(`[Lync] Lync.int: range [{min}, {max}] exceeds i32 bounds`)
+    Log.error(`range [{min}, {max}] exceeds i32 bounds`)
 end
 
 return table.freeze(Int)

package/src/codec/primitive/Number.luau

@@ -1,13 +1,15 @@
 --!strict
 --!optimize 2
--- Explicit-precision float codecs: f32 and f64.
+-- Explicit-precision float codecs: f32 (4B) and f64 (8B).
 
 local Base = require(script.Parent.Parent.Base)
 
--- Constants --------------------------------------------------------------
+-- State ------------------------------------------------------------------
 
--- Shared scratch for Auto codec's f32 round-trip test. Roblox is
--- single-threaded so a module-level scratch cannot be aliased.
+--[[
+    Roblox is single-threaded, so a module-level scratch is safe to alias.
+    Auto codec uses this to round-trip a float through f32 and check fidelity.
+]]
 local F32_SCRATCH = buffer.create(4)
 
 -- Public -----------------------------------------------------------------