tjbot-ce 3.0.1

package/dist/led/led-neopixel-spi.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright 2025 IBM Corp. All Rights Reserved.
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import SPI from 'pi-spi';
+/**
+ * LED controller for SPI-based NeoPixel LEDs (Raspberry Pi 5)
+ * This is based on pi5neo.py:
+ * https://github.com/vanshksingh/Pi5Neo/blob/main/pi5neo/pi5neo.py
+ */
+export declare class LEDNeopixelSPI {
+    spi: SPI.SPI;
+    useGRBFormat: boolean;
+    private isPrimed;
+    private static readonly HIGH;
+    private static readonly LOW;
+    private static readonly FREQ;
+    private static readonly RESET_BYTES;
+    private static readonly FRAME_REPEATS;
+    private static readonly PRIME_OFF_FRAMES;
+    private static readonly INTER_FRAME_DELAY_MS;
+    private static readonly PRIME_DELAY_MS;
+    private static isSPIEnabledFromConfig;
+    private static assertSPIEnabled;
+    private static isSPIEnabledInFirmwareConfig;
+    private static isGpio10MuxedForSPI;
+    private static assertSPIPreconditions;
+    constructor(spiInterface: string, useGRB?: boolean);
+    private static sleep;
+    private primeLink;
+    private transferFrame;
+    private buildFramedBitstream;
+    static bitMask(byte: number, index: number): boolean;
+    static byteToBitstream(byte: number): number[];
+    static rgbToSpiBitstream(red: number, green: number, blue: number, useGRB: boolean): Buffer;
+    /**
+     * Render the LED to a specified color.
+     * @param color The color to render, specified as a string of hexadecimal digits
+     * with no leading '0x' or '#' in RRGGBB format.
+     * @returns A promise that resolves when the SPI transfer completes.
+     */
+    render(color: string): Promise<void>;
+    /**
+     * Clean up resources
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=led-neopixel-spi.d.ts.map

package/dist/led/led-neopixel-spi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"led-neopixel-spi.d.ts","sourceRoot":"","sources":["../../src/led/led-neopixel-spi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,GAAG,MAAM,QAAQ,CAAC;AAMzB;;;;GAIG;AACH,qBAAa,cAAc;IACvB,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC;IACb,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAU;IAE1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAgB;IAC5C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAgB;IAC3C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAmB;IAC/C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAe;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAa;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAa;IACrD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAa;IACzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAa;IAEnD,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAarC,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAuB/B,OAAO,CAAC,MAAM,CAAC,4BAA4B;IAS3C,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAoBlC,OAAO,CAAC,MAAM,CAAC,sBAAsB;gBAkBzB,YAAY,EAAE,MAAM,EAAE,MAAM,GAAE,OAAe;IAazD,OAAO,CAAC,MAAM,CAAC,KAAK;YAIN,SAAS;YAUT,aAAa;IAiB3B,OAAO,CAAC,oBAAoB;IAW5B,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAIpD,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAY9C,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM;IAU3F;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B1C;;OAEG;IACH,OAAO,IAAI,IAAI;CAGlB"}

package/dist/led/led-neopixel-spi.js

@@ -0,0 +1,216 @@
+/**
+ * Copyright 2025 IBM Corp. All Rights Reserved.
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import SPI from 'pi-spi';
+import { TJBotError } from '../utils/errors.js';
+import { getLogger } from '../utils/logging.js';
+const logger = getLogger(import.meta.url);
+/**
+ * LED controller for SPI-based NeoPixel LEDs (Raspberry Pi 5)
+ * This is based on pi5neo.py:
+ * https://github.com/vanshksingh/Pi5Neo/blob/main/pi5neo/pi5neo.py
+ */
+export class LEDNeopixelSPI {
+    spi;
+    useGRBFormat;
+    isPrimed;
+    static HIGH = 0xf8; // possibles: F0, F8, FC
+    static LOW = 0xc0; // possibles: C0
+    static FREQ = 6400000;
+    static RESET_BYTES = 100;
+    static FRAME_REPEATS = 2;
+    static PRIME_OFF_FRAMES = 6;
+    static INTER_FRAME_DELAY_MS = 1;
+    static PRIME_DELAY_MS = 2;
+    static isSPIEnabledFromConfig(configPath) {
+        if (!existsSync(configPath)) {
+            return null;
+        }
+        try {
+            const config = readFileSync(configPath, 'utf8');
+            return /^\s*dtparam\s*=\s*spi\s*=\s*on\s*$/m.test(config);
+        }
+        catch {
+            return null;
+        }
+    }
+    static assertSPIEnabled(spiInterface) {
+        const firmwareConfig = '/boot/firmware/config.txt';
+        const legacyConfig = '/boot/config.txt';
+        const fwEnabled = LEDNeopixelSPI.isSPIEnabledFromConfig(firmwareConfig);
+        const legacyEnabled = LEDNeopixelSPI.isSPIEnabledFromConfig(legacyConfig);
+        // If either known config explicitly enables SPI, accept.
+        if (fwEnabled === true || legacyEnabled === true) {
+            return;
+        }
+        // If a matching spidev node exists, SPI is effectively available.
+        if (existsSync(spiInterface)) {
+            return;
+        }
+        throw new TJBotError(`SPI appears to be disabled or unavailable (missing ${spiInterface}). ` +
+            'To enable SPI, edit /boot/firmware/config.txt and set dtparam=spi=on, then reboot your Raspberry Pi.');
+    }
+    static isSPIEnabledInFirmwareConfig() {
+        try {
+            const config = readFileSync('/boot/firmware/config.txt', 'utf8');
+            return /^\s*dtparam\s*=\s*spi\s*=\s*on\s*$/m.test(config);
+        }
+        catch {
+            return true;
+        }
+    }
+    static isGpio10MuxedForSPI() {
+        try {
+            const output = execSync('pinctrl get 10', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+            const lower = output.toLowerCase();
+            if (lower.includes('= none')) {
+                return false;
+            }
+            if (lower.includes('spi')) {
+                return true;
+            }
+            // On Raspberry Pi 5, SPI0 MOSI on GPIO10 is often ALT3 (shown as a3).
+            if (lower.includes(' a3 ') || lower.includes(' a3|') || lower.includes(' a3\t') || lower.includes(': a3')) {
+                return true;
+            }
+            return true;
+        }
+        catch {
+            return true;
+        }
+    }
+    static assertSPIPreconditions(spiInterface) {
+        LEDNeopixelSPI.assertSPIEnabled(spiInterface);
+        if (!LEDNeopixelSPI.isSPIEnabledInFirmwareConfig()) {
+            throw new TJBotError('SPI appears disabled in /boot/firmware/config.txt (dtparam=spi=on not set). ' +
+                'Enable SPI in /boot/firmware/config.txt, reboot, then retry.');
+        }
+        if (!LEDNeopixelSPI.isGpio10MuxedForSPI()) {
+            throw new TJBotError('GPIO10 is not currently muxed for SPI (pinctrl reports none). ' +
+                'Enable SPI in /boot/firmware/config.txt (dtparam=spi=on), reboot, then retry.');
+        }
+    }
+    constructor(spiInterface, useGRB = false) {
+        const i = spiInterface || '/dev/spidev0.0';
+        LEDNeopixelSPI.assertSPIPreconditions(i);
+        this.spi = SPI.initialize(i);
+        this.spi.clockSpeed(LEDNeopixelSPI.FREQ);
+        this.spi.dataMode(0);
+        this.spi.bitOrder(SPI.order.MSB_FIRST);
+        this.useGRBFormat = useGRB;
+        this.isPrimed = false;
+        logger.verbose(`Initialized NeoPixel SPI LED on interface ${i} with GRB format: ${useGRB}`);
+    }
+    static sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    async primeLink() {
+        logger.debug('Priming NeoPixel SPI link with OFF frames');
+        const offFrame = this.buildFramedBitstream('000000');
+        for (let i = 0; i < LEDNeopixelSPI.PRIME_OFF_FRAMES; i++) {
+            await this.transferFrame(offFrame);
+            await LEDNeopixelSPI.sleep(LEDNeopixelSPI.PRIME_DELAY_MS);
+        }
+        logger.debug('NeoPixel SPI link prime complete');
+    }
+    async transferFrame(bitstream) {
+        for (let i = 0; i < LEDNeopixelSPI.FRAME_REPEATS; i++) {
+            await new Promise((resolve, reject) => {
+                this.spi.transfer(bitstream, (err) => {
+                    if (err) {
+                        logger.error('SPI transfer error:', err);
+                        reject(new TJBotError('SPI transfer failed', { cause: err }));
+                    }
+                    else {
+                        logger.debug('LEDNeopixelSPI.render spi.transfer success');
+                        resolve();
+                    }
+                });
+            });
+            await LEDNeopixelSPI.sleep(LEDNeopixelSPI.INTER_FRAME_DELAY_MS);
+        }
+    }
+    buildFramedBitstream(color) {
+        const c = parseInt(color, 16);
+        const r = (c & 0xff0000) >> 16;
+        const g = (c & 0x00ff00) >> 8;
+        const b = c & 0x0000ff;
+        const colorFrame = LEDNeopixelSPI.rgbToSpiBitstream(r, g, b, this.useGRBFormat);
+        const resetBuf = Buffer.alloc(LEDNeopixelSPI.RESET_BYTES, 0x00);
+        return Buffer.concat([resetBuf, colorFrame, resetBuf]);
+    }
+    static bitMask(byte, index) {
+        return (byte & (1 << (7 - index))) !== 0;
+    }
+    static byteToBitstream(byte) {
+        // Initialize with low bits
+        const bitstream = Array(8).fill(LEDNeopixelSPI.LOW);
+        for (let i = 0; i < 8; i++) {
+            if (LEDNeopixelSPI.bitMask(byte, i)) {
+                // Set high bits for '1'
+                bitstream[i] = LEDNeopixelSPI.HIGH;
+            }
+        }
+        return bitstream;
+    }
+    static rgbToSpiBitstream(red, green, blue, useGRB) {
+        const red_bits = LEDNeopixelSPI.byteToBitstream(red);
+        const green_bits = LEDNeopixelSPI.byteToBitstream(green);
+        const blue_bits = LEDNeopixelSPI.byteToBitstream(blue);
+        const bitstream = useGRB
+            ? Buffer.from(green_bits.concat(red_bits).concat(blue_bits))
+            : Buffer.from(red_bits.concat(green_bits).concat(blue_bits));
+        return bitstream;
+    }
+    /**
+     * Render the LED to a specified color.
+     * @param color The color to render, specified as a string of hexadecimal digits
+     * with no leading '0x' or '#' in RRGGBB format.
+     * @returns A promise that resolves when the SPI transfer completes.
+     */
+    async render(color) {
+        logger.debug(`Rendering NeoPixel LED (SPI) with color: ${color}`);
+        try {
+            if (!this.isPrimed) {
+                await this.primeLink();
+                this.isPrimed = true;
+            }
+            const bitstream = this.buildFramedBitstream(color);
+            // Transfer data via SPI to update the LED
+            // Wait for the transfer to complete before returning
+            logger.debug('LEDNeopixelSPI.render about to call spi.transfer');
+            await this.transferFrame(bitstream);
+            logger.debug('LEDNeopixelSPI.render completed normally');
+        }
+        catch (e) {
+            logger.error('Exception in LEDNeopixelSPI.render:', e);
+            // Print stack trace if available
+            if (e instanceof Error && e.stack) {
+                logger.error(e.stack);
+            }
+            throw e;
+        }
+    }
+    /**
+     * Clean up resources
+     */
+    cleanup() {
+        logger.debug('LEDNeopixelSPI cleanup (no-op)');
+    }
+}
+//# sourceMappingURL=led-neopixel-spi.js.map

package/dist/led/led-neopixel-spi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"led-neopixel-spi.js","sourceRoot":"","sources":["../../src/led/led-neopixel-spi.ts"],"names":[],"mappings":"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"}

package/dist/led/led-neopixel-ws281x.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+/**
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * NeoPixel root helper process.
+ *
+ * This process is launched as root (via sudo) by LEDNeopixel to gain access to
+ * rpi-ws281x-native, which requires root privileges on RPi 3/4.
+ *
+ * Protocol: newline-delimited JSON on stdin/stdout.
+ *   Requests:
+ *     { id, cmd: "init",     pin, numLeds }
+ *     { id, cmd: "render",   color }        -- color is a 32-bit integer (0xRRGGBB)
+ *     { id, cmd: "reset"  }
+ *     { id, cmd: "shutdown" }
+ *   Responses:
+ *     { id, ok: true }
+ *     { id, ok: false, error: "<message>" }
+ *
+ * stderr is for human-readable diagnostics only and does not affect the protocol.
+ */
+
+import { createRequire } from 'module';
+
+// rpi-ws281x-native is a native CJS addon; load it via createRequire so this
+// file can remain an ES module (.js with "type":"module" in package.json).
+const require = createRequire(import.meta.url);
+const ws281x = require('rpi-ws281x-native');
+
+const LED_DMA = 10;
+const LED_FREQ_HZ = 800000;
+const LED_BRIGHTNESS = 255;
+const LED_INVERT = false;
+const LED_STRIP_TYPE = ws281x.stripType.WS2812;
+
+let initialized = false;
+let channel;
+
+/**
+ * Reply with a structured JSON response on stdout.
+ * @param {number|string} id
+ * @param {boolean} ok
+ * @param {string|undefined} error
+ */
+function reply(id, ok, error) {
+    const msg = ok ? { id, ok: true } : { id, ok: false, error: String(error ?? 'unknown error') };
+    process.stdout.write(JSON.stringify(msg) + '\n');
+}
+
+/**
+ * Handle a single parsed command object.
+ * @param {{ id: number|string, cmd: string, pin?: number, numLeds?: number, color?: number }} req
+ */
+function handle(req) {
+    const { id, cmd } = req;
+
+    try {
+        switch (cmd) {
+            case 'init': {
+                const pin = Number(req.pin);
+                const numLeds = Number(req.numLeds ?? 1);
+                if (!Number.isInteger(pin) || pin < 0 || pin > 40) {
+                    reply(id, false, `invalid pin: ${req.pin}`);
+                    return;
+                }
+                channel = ws281x(numLeds, {
+                    gpio: pin,
+                    dma: LED_DMA,
+                    freq: LED_FREQ_HZ,
+                    invert: LED_INVERT,
+                    brightness: LED_BRIGHTNESS,
+                    stripType: LED_STRIP_TYPE,
+                });
+                initialized = true;
+                reply(id, true);
+                break;
+            }
+
+            case 'render': {
+                if (!initialized) {
+                    reply(id, false, 'not initialized');
+                    return;
+                }
+                const color = Number(req.color);
+                if (!Number.isInteger(color) || color < 0 || color > 0xffffff) {
+                    reply(id, false, `invalid color: ${req.color}`);
+                    return;
+                }
+                channel.array[0] = color;
+                ws281x.render();
+                reply(id, true);
+                break;
+            }
+
+            case 'reset': {
+                if (initialized) {
+                    ws281x.reset();
+                }
+                reply(id, true);
+                break;
+            }
+
+            case 'shutdown': {
+                if (initialized) {
+                    ws281x.reset();
+                    ws281x.finalize();
+                    initialized = false;
+                    channel = undefined;
+                }
+                reply(id, true);
+                // Give stdout a chance to flush before exiting.
+                process.stdout.once('drain', () => process.exit(0));
+                // Force exit if drain takes too long (e.g. pipe already closed).
+                setTimeout(() => process.exit(0), 200).unref();
+                break;
+            }
+
+            default:
+                reply(id, false, `unknown command: ${cmd}`);
+        }
+    } catch (err) {
+        reply(id, false, String(err));
+    }
+}
+
+// --- Stdin line reader ---
+let buffer = '';
+
+process.stdin.setEncoding('utf8');
+
+process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (!line) continue;
+        try {
+            const req = JSON.parse(line);
+            handle(req);
+        } catch (_) {
+            // Malformed JSON — no id to reply to, so silently ignore.
+        }
+    }
+});
+
+process.stdin.on('end', () => {
+    // Parent closed the pipe — clean up and exit.
+    if (initialized) {
+        try {
+            ws281x.reset();
+            ws281x.finalize();
+        } catch (_) {
+            /* best effort */
+        }
+    }
+    process.exit(0);
+});
+
+// Ensure the helper does not keep a stale process alive if the parent dies.
+process.on('SIGTERM', () => {
+    if (initialized) {
+        try {
+            ws281x.reset();
+            ws281x.finalize();
+        } catch (_) {
+            /* best effort */
+        }
+    }
+    process.exit(0);
+});

package/dist/led/led-neopixel.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright 2025 IBM Corp. All Rights Reserved.
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * LED controller for NeoPixel (WS281x) LEDs on Raspberry Pi 3/4.
+ *
+ * rpi-ws281x-native requires root privileges. Rather than launching every
+ * TJBot recipe that uses the LED as root, this class spawns a small, long-lived
+ * helper process (in led-neopixel-ws281x.js) using sudo and communicates with it
+ * over a newline-delimited JSON IPC channel on stdin/stdout.
+ *
+ * Sudo authentication is performed once at construction time (either
+ * passwordless or via an interactive prompt). Subsequent render() calls are
+ * cheap IPC messages with no additional privilege escalation.
+ */
+export declare class LEDNeopixel {
+    private helper;
+    private reader?;
+    private helperStderrTail;
+    private _ready;
+    private _pendingById;
+    private _nextId;
+    private _helperDead;
+    constructor(pin: number);
+    /**
+     * Wait for the NeoPixel helper to be fully initialized and ready.
+     * Call this before loading long-running tasks if the LED needs to be available early.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Render the NeoPixel to a specific color.
+     * @param color Color as a 32-bit integer in RGB format (0xRRGGBB)
+     */
+    render(color: number): Promise<void>;
+    /**
+     * Send a reset command and terminate the helper process.
+     */
+    cleanup(): Promise<void>;
+    private _handleLine;
+    private _send;
+    private _setHelperHandleRefState;
+    private _killHelper;
+}
+//# sourceMappingURL=led-neopixel.d.ts.map

package/dist/led/led-neopixel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"led-neopixel.d.ts","sourceRoot":"","sources":["../../src/led/led-neopixel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAwBH;;;;;;;;;;;GAWG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAC,CAAY;IAC3B,OAAO,CAAC,gBAAgB,CAAgB;IACxC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,YAAY,CAA0C;IAC9D,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,WAAW,CAAsB;gBAE7B,GAAG,EAAE,MAAM;IA+FvB;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1C;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAY9B,OAAO,CAAC,WAAW;IA4BnB,OAAO,CAAC,KAAK;IA0Bb,OAAO,CAAC,wBAAwB;IAqBhC,OAAO,CAAC,WAAW;CAYtB"}