@yodaos-pkg/ink-env 0.14.0-daily.202606291604

package/README.md

@@ -0,0 +1,185 @@
+# @yodaos-pkg/ink-env
+
+`@yodaos-pkg/ink-env` provides TypeScript ambient type definitions for the Ink JavaScript runtime environment.
+
+It is intended for JavaScript and TypeScript application code that runs inside Ink. The package focuses on the API surface available to app code and intentionally does not document runtime implementation details.
+
+## What This Package Provides
+
+- global environment types such as `console`, timers, `fetch`, `WebSocket`, `EventSource`, `navigator`, and `performance`
+- DOM-style event and event target types used by the Ink runtime
+- app-facing framework globals such as `getApp()`, `App`, `Page`, and `Component`
+- the `wx` namespace for mini-program style APIs
+- media, speech, sensor, networking, and AI-related API typings exposed to business logic
+- asset module declarations for common image and audio file types
+
+## Install
+
+```bash
+npm install -D @yodaos-pkg/ink-env
+```
+
+This package exposes global declarations. In most cases you do not need to import anything from it.
+
+## TypeScript Setup
+
+Add the package to your `tsconfig.json` so TypeScript can load the ambient declarations explicitly:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@yodaos-pkg/ink-env"]
+  }
+}
+```
+
+If your project already loads all installed type packages automatically, this step may not be necessary.
+
+## API Overview
+
+### Core Globals
+
+The environment includes commonly used global APIs such as:
+
+- `console`
+- `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`
+- `requestAnimationFrame`, `cancelAnimationFrame`
+- `atob`, `btoa`
+- `fetch`, `RequestInit`, `Response`
+- `Blob`, `ImageBitmap`, `ImageData`, `createImageBitmap`
+- `window`, `self`, `global`, `performance`
+
+Example:
+
+```ts
+setTimeout(() => {
+  console.log('hello from Ink');
+}, 16);
+```
+
+### App And Page APIs
+
+The package includes framework-facing globals and instance types used by application code:
+
+- `getApp()`
+- `App`
+- `Page`
+- `Component`
+
+These types are useful for page logic, component logic, and app-level state access.
+
+### DOM-Style Events
+
+Ink application code can use DOM-like event primitives and typed event objects, including:
+
+- `EventTarget`
+- `Event`
+- `MessageEvent`
+- `KeyboardEvent`
+- `PointerEvent`
+- `WheelEvent`
+- `FocusEvent`
+- `InputEvent`
+
+These declarations are designed for app code that listens to runtime-dispatched events or interacts with event-driven APIs.
+
+### Networking APIs
+
+The environment includes typed networking surfaces for both promise-based and streaming use cases:
+
+- `fetch()`
+- `WebSocket`
+- `EventSource`
+- `AbortController` and `AbortSignal`
+
+Example:
+
+```ts
+const response = await fetch('https://example.com/data');
+const data = await response.json();
+console.log(data);
+```
+
+### Navigator And Runtime Information
+
+The `navigator` typing includes runtime and device-facing information such as:
+
+- `navigator.userAgent`
+- `navigator.language`
+- `navigator.languages`
+- `navigator.region`
+- `navigator.versions`
+- `navigator.bluetooth`
+
+### Media And Audio APIs
+
+The package includes types for media-related capabilities exposed to app code, such as:
+
+- `AudioPlayer`
+- `Sound`
+- `createImageBitmap`
+- recorder and camera APIs under `wx.media`
+
+### Sensors And Speech APIs
+
+The environment also includes typed interfaces for selected device capabilities:
+
+- `Accelerometer`
+- `Gyroscope`
+- `Magnetometer`
+- `AbsoluteOrientationSensor`
+- `SpeechRecognition`
+- `wx.speech`
+
+Availability may depend on the current host environment. The type package describes the supported JavaScript API surface, not host-by-host runtime guarantees.
+
+### AI APIs
+
+The package includes AI-related types exposed to application code:
+
+- `LanguageModel`
+- `LanguageModelSession`
+- `LanguageModelMessage`
+- `LanguageModelTool`
+
+These types are intended for application code that interacts with the host-provided language model capability.
+
+### `wx` Namespace
+
+Mini-program style APIs are exposed under the global `wx` namespace. Current type coverage includes areas such as:
+
+- base utilities like `wx.canIUse()`
+- window and system information such as `wx.getWindowInfo()`
+- app control such as `wx.exitMiniProgram()`
+- UI helpers such as `wx.setBackgroundColor()`
+- networking APIs such as `wx.request()`, `wx.connectSocket()`, and `wx.createEventSource()`
+- media APIs such as recorder and camera helpers under `wx.media`
+- speech helpers under `wx.speech`
+
+Example:
+
+```ts
+const info = wx.getWindowInfo();
+console.log(info.windowWidth, info.windowHeight);
+```
+
+## What This Package Does Not Cover
+
+This README is intentionally focused on the JavaScript and TypeScript API surface available to application code.
+
+It does not document:
+
+- runtime internals
+- renderer or engine architecture
+- native bridge details
+- package implementation structure
+- host-specific implementation notes that are not part of the exposed API contract
+
+## Files
+
+The published package contains:
+
+- `index.d.ts`
+- `globals.d.ts`
+- `wx.d.ts`
+- `README.md`