Initial commit: Text encoding component with UTF-8 polyfills

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

index.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Type declarations for @metatrom/text-encoding
+ * Self-contained for IOR type generation
+ */
+
+declare module '@metatrom/text-encoding' {
+  /**
+   * TextEncoder interface - encodes strings to UTF-8 byte arrays
+   */
+  export interface ITextEncoder {
+    /**
+     * The encoding format (always 'utf-8' for this implementation)
+     */
+    readonly encoding: string;
+
+    /**
+     * Encode a string into a Uint8Array using UTF-8 encoding
+     * @param input The string to encode
+     * @returns UTF-8 encoded byte array
+     */
+    encode(input?: string): Uint8Array;
+
+    /**
+     * Encode a string into an existing Uint8Array (partial encoding)
+     * @param source The string to encode
+     * @param destination The array to write to
+     * @returns Object with read (chars) and written (bytes) counts
+     */
+    encodeInto?(source: string, destination: Uint8Array): TextEncoderEncodeIntoResult;
+  }
+
+  /**
+   * TextDecoder interface - decodes UTF-8 byte arrays to strings
+   */
+  export interface ITextDecoder {
+    /**
+     * The encoding format (always 'utf-8' for this implementation)
+     */
+    readonly encoding: string;
+
+    /**
+     * Whether to throw on invalid sequences (vs replacement char)
+     */
+    readonly fatal: boolean;
+
+    /**
+     * Whether to ignore BOM (byte order mark)
+     */
+    readonly ignoreBOM: boolean;
+
+    /**
+     * Decode a byte array into a string using UTF-8 decoding
+     * @param input The bytes to decode (Uint8Array or ArrayBuffer)
+     * @param options Decoding options
+     * @returns Decoded string
+     */
+    decode(input?: ArrayBufferView | ArrayBuffer, options?: TextDecodeOptions): string;
+  }
+
+  /**
+   * Result of encodeInto operation
+   */
+  export interface TextEncoderEncodeIntoResult {
+    /**
+     * Number of UTF-16 code units read from source
+     */
+    read: number;
+
+    /**
+     * Number of bytes written to destination
+     */
+    written: number;
+  }
+
+  /**
+   * Options for text decoding
+   */
+  export interface TextDecodeOptions {
+    /**
+     * Whether this is a streaming decode (more data coming)
+     */
+    stream?: boolean;
+  }
+
+  /**
+   * Options for TextDecoder constructor
+   */
+  export interface TextDecoderOptions {
+    /**
+     * If true, throw on invalid byte sequences
+     */
+    fatal?: boolean;
+
+    /**
+     * If true, ignore byte order mark
+     */
+    ignoreBOM?: boolean;
+  }
+
+  /**
+   * Factory for creating encoder/decoder instances
+   */
+  export interface ITextEncodingFactory {
+    /**
+     * Create a new TextEncoder instance
+     */
+    createEncoder(): ITextEncoder;
+
+    /**
+     * Create a new TextDecoder instance
+     * @param label Encoding label (default 'utf-8')
+     * @param options Decoder options
+     */
+    createDecoder(label?: string, options?: TextDecoderOptions): ITextDecoder;
+
+    /**
+     * Check if TextEncoder/TextDecoder are natively available
+     */
+    isNativelySupported(): boolean;
+  }
+
+  /**
+   * Text encoding service for shared instances
+   */
+  export interface ITextEncodingService {
+    /**
+     * Shared encoder instance
+     */
+    readonly encoder: ITextEncoder;
+
+    /**
+     * Shared decoder instance
+     */
+    readonly decoder: ITextDecoder;
+
+    /**
+     * Encode string to bytes
+     */
+    encode(text: string): Uint8Array;
+
+    /**
+     * Decode bytes to string
+     */
+    decode(bytes: Uint8Array | ArrayBuffer | number[]): string;
+
+    /**
+     * Convert string to UTF-8 byte array (convenience method)
+     */
+    stringToUtf8(text: string): Uint8Array;
+
+    /**
+     * Convert UTF-8 byte array to string (convenience method)
+     */
+    utf8ToString(bytes: Uint8Array | number[]): string;
+  }
+
+  /**
+   * TextEncoder Polyfill Implementation
+   */
+  export declare class TextEncoderPolyfill implements ITextEncoder {
+    readonly encoding: string;
+    encode(input?: string): Uint8Array;
+    encodeInto(source: string, destination: Uint8Array): TextEncoderEncodeIntoResult;
+  }
+
+  /**
+   * TextDecoder Polyfill Implementation
+   */
+  export declare class TextDecoderPolyfill implements ITextDecoder {
+    readonly encoding: string;
+    readonly fatal: boolean;
+    readonly ignoreBOM: boolean;
+    
+    constructor(label?: string, options?: TextDecoderOptions);
+    decode(input?: ArrayBufferView | ArrayBuffer | null, options?: TextDecodeOptions): string;
+  }
+
+  /**
+   * Text Encoding Factory
+   */
+  export declare class TextEncodingFactory implements ITextEncodingFactory {
+    static getInstance(): TextEncodingFactory;
+    createEncoder(): ITextEncoder;
+    createDecoder(label?: string, options?: TextDecoderOptions): ITextDecoder;
+    isNativelySupported(): boolean;
+  }
+
+  /**
+   * Text Encoding Service Implementation
+   */
+  export declare class TextEncodingService implements ITextEncodingService {
+    readonly encoder: ITextEncoder;
+    readonly decoder: ITextDecoder;
+    
+    encode(text: string): Uint8Array;
+    decode(bytes: Uint8Array | ArrayBuffer | number[]): string;
+    stringToUtf8(text: string): Uint8Array;
+    utf8ToString(bytes: Uint8Array | number[]): string;
+  }
+
+  /**
+   * Factory functions
+   */
+  export function createTextEncoder(): ITextEncoder;
+  export function createTextDecoder(label?: string, options?: TextDecoderOptions): ITextDecoder;
+  export function installTextEncodingPolyfills(): void;
+  export function getTextEncodingService(): ITextEncodingService;
+
+  /**
+   * Default shared text encoding service
+   * Use this for most encoding/decoding needs
+   */
+  export const textEncoding: ITextEncodingService;
+
+  /**
+   * Version information
+   */
+  export const VERSION: string;
+  export const COMPONENT_NAME: string;
+}