docs: update llms.txt and README.md to use idiomatic APIs

Remove all capi/ fallback patterns now that hwbuf.Allocate, buf.Lock,
buf.Describe, hwbuf.RecvHandleFromUnixSocket, codec.DequeueInputBuffer,
codec.DequeueOutputBuffer, and media.BufferInfo are in the idiomatic
layer. Update the "Idiomatic vs capi" sections, buffer processing loop,
allocate-lock-unlock lifecycle, and IPC sharing examples.

Author: xaionaro@dx.center

README.md

@@ -76,18 +76,22 @@ All three libraries talk to the same Android system services, but through differ
 
 Always import the **idiomatic top-level packages** (`github.com/AndroidGoLab/ndk/{module}`) in your application code. These provide Go-friendly types with proper lifecycle management (`Close()`, `defer`), typed error handling, and method receivers.
 
-The `capi/` packages (`github.com/AndroidGoLab/ndk/capi/{module}`) are the raw CGo bindings generated in Stage 2 of the pipeline. They mirror the C API directly — C-style function names, `unsafe.Pointer` parameters, raw integer return codes. **They are intended for power users** who need access to NDK functions not yet wrapped by the idiomatic layer. A few functions (e.g., `AHardwareBuffer_allocate`, `AHardwareBuffer_lock`, `AMediaCodec_dequeueInputBuffer`) are not yet exposed idiomatically and require a `capi/` import as a temporary fallback.
-
-When using `capi/` functions, wrap the resulting C pointers in idiomatic types as soon as possible:
+The `capi/` packages (`github.com/AndroidGoLab/ndk/capi/{module}`) are the raw CGo bindings generated in Stage 2 of the pipeline. They mirror the C API directly — C-style function names, `unsafe.Pointer` parameters, raw integer return codes. **They are intended for power users** who need access to NDK functions not yet wrapped by the idiomatic layer. All commonly used functions — including `hwbuf.Allocate`, `buf.Lock`, `codec.DequeueInputBuffer`, and `codec.DequeueOutputBuffer` — are available in the idiomatic layer.
 
 ```go
-import capihw "github.com/AndroidGoLab/ndk/capi/hardwarebuffer"
+import "github.com/AndroidGoLab/ndk/hwbuf"
 
-// Advanced: allocate via capi, then wrap in idiomatic type
-var rawBuf *capihw.AHardwareBuffer
-capihw.AHardwareBuffer_allocate(&desc, &rawBuf)
-buf := hwbuf.NewBufferFromPointer(unsafe.Pointer(rawBuf))
-defer buf.Close()  // use idiomatic lifecycle from here on
+// Allocate a hardware buffer using the idiomatic API
+desc := hwbuf.Desc{
+    Width: 1920, Height: 1080, Layers: 1,
+    Format: uint32(hwbuf.R8g8b8a8Unorm),
+    Usage:  uint64(hwbuf.CpuWriteOften | hwbuf.GpuSampledImage),
+}
+buf, err := hwbuf.Allocate(&desc)
+if err != nil {
+    log.Fatal(err)
+}
+defer buf.Close()
 ```
 
 ## Examples

llms.txt

@@ -4,7 +4,7 @@
 
 ## Idiomatic vs capi Packages
 
-Always import the idiomatic top-level packages (`github.com/AndroidGoLab/ndk/{module}`) — not the `capi/` packages. The `capi/` layer is a raw CGo binding with C-style names and unsafe types; it is intended only for power users who need NDK functions not yet wrapped by the idiomatic layer. A few functions (e.g., `AMediaCodec_dequeueInputBuffer`, `AHardwareBuffer_allocate`, `AHardwareBuffer_lock`) are not yet exposed idiomatically and require a `capi/` import as a temporary fallback. These cases are marked "**Advanced (capi)**" below.
+Always import the idiomatic top-level packages (`github.com/AndroidGoLab/ndk/{module}`) — not the `capi/` packages. The `capi/` layer is a raw CGo binding with C-style names and unsafe types; it is intended only for power users who need NDK functions not yet wrapped by the idiomatic layer. All commonly used functions — including `hwbuf.Allocate`, `buf.Lock`, `codec.DequeueInputBuffer`, `codec.DequeueOutputBuffer`, and `hwbuf.RecvHandleFromUnixSocket` — are available in the idiomatic layer.
 
 ## Resource Lifecycle and Memory Management
 
@@ -624,23 +624,17 @@ Format keys are passed as strings to `SetInt32`/`SetString`/`SetFloat`/`SetInt64
 
 ### Buffer Processing Loop
 
-The idiomatic `media` package provides `GetInputBuffer`, `QueueInputBuffer`, `GetOutputBuffer`, `ReleaseOutputBuffer`, and all constants (`media.AMEDIACODEC_INFO_*`, `media.AMEDIACODEC_BUFFER_FLAG_*`). The `DequeueInputBuffer` and `DequeueOutputBuffer` functions are not yet in the idiomatic layer and require a `capi/media` import (see **Advanced** note below).
-
-The dequeue functions (`DequeueInputBuffer`, `DequeueOutputBuffer`) are not yet in the idiomatic layer and require a `capi/media` import. All other buffer operations use the idiomatic `media` package.
+The idiomatic `media` package provides all buffer processing functions: `DequeueInputBuffer`, `DequeueOutputBuffer`, `GetInputBuffer`, `QueueInputBuffer`, `GetOutputBuffer`, `ReleaseOutputBuffer`, and all constants (`media.AMEDIACODEC_INFO_*`, `media.AMEDIACODEC_BUFFER_FLAG_*`). The `media.BufferInfo` value struct is used with `DequeueOutputBuffer`.
 
 ```go
 import (
     "unsafe"
     "github.com/AndroidGoLab/ndk/media"
-    capimedia "github.com/AndroidGoLab/ndk/capi/media"  // needed for dequeue (not yet idiomatic)
 )
 
-// Get the raw capi pointer for dequeue calls
-rawCodec := (*capimedia.AMediaCodec)(codec.Pointer())
-
 for {
-    // 1. Dequeue input buffer (capi — not yet in idiomatic layer)
-    idx := capimedia.AMediaCodec_dequeueInputBuffer(rawCodec, timeoutUs)
+    // 1. Dequeue input buffer
+    idx := codec.DequeueInputBuffer(timeoutUs)
     if idx < 0 { continue }  // no buffer available yet
 
     // 2. Fill with data (NAL units for video, PCM for audio)
@@ -649,25 +643,25 @@ for {
     data := unsafe.Slice(buf, bufSize)
     n := copy(data, inputFrame)
 
-    // 3. Queue for processing (idiomatic)
+    // 3. Queue for processing
     codec.QueueInputBuffer(uint64(idx), 0, uint64(n), presentationTimeUs, 0)
     // End of stream: pass uint32(media.AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM)
 
-    // 4. Dequeue output buffer (capi — not yet in idiomatic layer)
-    var info capimedia.AMediaCodecBufferInfo
-    outIdx := capimedia.AMediaCodec_dequeueOutputBuffer(rawCodec, &info, timeoutUs)
+    // 4. Dequeue output buffer with BufferInfo
+    var info media.BufferInfo
+    outIdx := codec.DequeueOutputBuffer(&info, timeoutUs)
     if outIdx == int64(media.AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED) {
         continue  // output format changed, query new format
     }
     if outIdx < 0 { continue }
 
-    // 5. Consume output (idiomatic)
+    // 5. Consume output — info.Offset, info.Size, info.PresentationTimeUs, info.Flags
     var outSize uint64
     outBuf := codec.GetOutputBuffer(uint64(outIdx), &outSize)
     outData := unsafe.Slice(outBuf, outSize)
     processOutput(outData)
 
-    // 6. Release back to codec (idiomatic; render=true to send to surface)
+    // 6. Release back to codec (render=true to send to surface)
     codec.ReleaseOutputBuffer(uint64(outIdx), false)
 }
 ```
@@ -1117,62 +1111,58 @@ Wraps the NDK `AHardwareBuffer` API for GPU/CPU-shared buffers. Lifecycle: Descr
 
 ### Idiomatic Buffer Usage
 
-The idiomatic `hwbuf` package provides the `Buffer` type with `Acquire`, `Unlock`, `LockPlanes`, `SendHandleToUnixSocket`, `GetID`, and `Close` methods, plus all format and usage constants.
+The idiomatic `hwbuf` package provides the full hardware buffer API: `Allocate`, `Lock`, `Describe`, `Acquire`, `Unlock`, `LockPlanes`, `SendHandleToUnixSocket`, `RecvHandleFromUnixSocket`, `IsSupported`, `GetID`, and `Close`, plus all format and usage constants. The `hwbuf.Desc` value struct has exported fields (Width, Height, Layers, Format, Usage, Stride, Rfu0, Rfu1) using raw uint32/uint64 types for layout compatibility.
 
 ```go
 import "github.com/AndroidGoLab/ndk/hwbuf"
 
-// Once you have a Buffer (from another API or via capi allocation below):
-buf.Acquire()          // increment ref count for sharing
-buf.Unlock(nil)        // release CPU mapping (nil = synchronous)
+// Allocate and lifecycle
+buf, err := hwbuf.Allocate(&desc)  // allocate a new hardware buffer
+buf.Describe()                      // get buffer description (*hwbuf.Desc)
+buf.Lock(usage, fence, rect)        // lock for CPU access (returns unsafe.Pointer)
+buf.Acquire()                       // increment ref count for sharing
+buf.Unlock(nil)                     // release CPU mapping (nil = synchronous)
 buf.LockPlanes(usage, fence, rect, outPlanes) // multi-plane lock (YUV)
 buf.SendHandleToUnixSocket(socketFd)          // IPC sharing
-buf.GetID(&id)         // get unique buffer ID
-buf.Close()            // decrement ref count, free when zero
+hwbuf.RecvHandleFromUnixSocket(socketFd)      // IPC receive
+hwbuf.IsSupported(&desc)                      // check if config is supported
+buf.GetID(&id)                                // get unique buffer ID
+buf.Close()                                   // decrement ref count, free when zero
 ```
 
-### Advanced (capi): Allocate-Lock-Unlock Lifecycle
+### Allocate-Lock-Unlock Lifecycle
 
-`AHardwareBuffer_allocate` and `AHardwareBuffer_lock` are not yet in the idiomatic layer and require the `capi/hardwarebuffer` package. Once allocated, wrap with `hwbuf.NewBufferFromPointer` for idiomatic usage.
+The idiomatic `hwbuf` package provides `hwbuf.Desc` (a value struct with exported fields), `hwbuf.Allocate`, and `buf.Lock` for the full allocate-lock-unlock lifecycle. No `capi/` import is needed.
 
 ```go
 import (
     "unsafe"
     "github.com/AndroidGoLab/ndk/hwbuf"
-    capihw "github.com/AndroidGoLab/ndk/capi/hardwarebuffer"
 )
 
-// 1. Describe: fill the buffer descriptor (capi struct)
-desc := capihw.AHardwareBuffer_Desc{
+// 1. Describe: fill the buffer descriptor (idiomatic value struct)
+//    Fields use raw uint32/uint64 for layout compatibility; cast enum constants.
+desc := hwbuf.Desc{
     Width:  1920,
     Height: 1080,
     Layers: 1,
-    Format: uint32(hwbuf.R8g8b8a8Unorm),  // idiomatic constant
-    Usage:  uint64(hwbuf.CpuWriteOften | hwbuf.GpuSampledImage),  // idiomatic constants
+    Format: uint32(hwbuf.R8g8b8a8Unorm),
+    Usage:  uint64(hwbuf.CpuWriteOften | hwbuf.GpuSampledImage),
 }
 
-// 2. Allocate (capi — wraps AHardwareBuffer_allocate)
-var rawBuf *capihw.AHardwareBuffer
-rc := capihw.AHardwareBuffer_allocate(&desc, &rawBuf)
-if rc != 0 {
-    log.Fatalf("AHardwareBuffer_allocate failed: %d", rc)
+// 2. Allocate — returns an idiomatic *hwbuf.Buffer directly
+buf, err := hwbuf.Allocate(&desc)
+if err != nil {
+    log.Fatalf("hwbuf.Allocate failed: %v", err)
 }
-// Wrap in idiomatic Buffer for lifecycle management
-buf := hwbuf.NewBufferFromPointer(unsafe.Pointer(rawBuf))
 defer buf.Close()  // decrements ref count, frees when zero
 
-// 3. Lock for CPU access (capi — wraps AHardwareBuffer_lock)
+// 3. Lock for CPU access
 //    usage must be a subset of allocation usage flags.
 //    fence=-1 means no fence; rect=nil means full buffer.
-var pixelPtr unsafe.Pointer
-rc = capihw.AHardwareBuffer_lock(rawBuf,
-    uint64(hwbuf.CpuWriteOften),  // CPU write access
-    -1,                            // fence fd (-1 = none)
-    nil,                           // rect (nil = full buffer)
-    &pixelPtr,
-)
-if rc != 0 {
-    log.Fatalf("AHardwareBuffer_lock failed: %d", rc)
+pixelPtr, err := buf.Lock(uint64(hwbuf.CpuWriteOften), -1, nil)
+if err != nil {
+    log.Fatalf("buf.Lock failed: %v", err)
 }
 
 // 4. Access: read/write pixel data via the mapped pointer
@@ -1188,7 +1178,7 @@ for y := 0; y < 1080; y++ {
     }
 }
 
-// 5. Unlock via idiomatic method (nil fence = synchronous)
+// 5. Unlock (nil fence = synchronous)
 if err := buf.Unlock(nil); err != nil {
     log.Fatalf("unlock: %v", err)
 }
@@ -1234,15 +1224,14 @@ hwbuf.CpuWriteOften | hwbuf.VideoEncode
 ### IPC: Sharing Between Processes
 
 ```go
-// Sender process (idiomatic):
+// Sender process:
 buf.SendHandleToUnixSocket(socketFd)
 
-// Receiver process (capi — not yet in idiomatic layer):
-import capihw "github.com/AndroidGoLab/ndk/capi/hardwarebuffer"
-
-var recvBuf *capihw.AHardwareBuffer
-capihw.AHardwareBuffer_recvHandleFromUnixSocket(socketFd, &recvBuf)
-received := hwbuf.NewBufferFromPointer(unsafe.Pointer(recvBuf))
+// Receiver process:
+received, err := hwbuf.RecvHandleFromUnixSocket(socketFd)
+if err != nil {
+    log.Fatalf("recv handle: %v", err)
+}
 defer received.Close()
 ```