react-pebble 0.1.0

package/src/pebble-render.ts

@@ -0,0 +1,311 @@
+/**
+ * pebble-render.ts — Entry point for react-pebble on Pebble Alloy.
+ *
+ * Bridges Preact's output (via a DOM-shim over pebble-dom) to Moddable's
+ * Poco renderer, which draws into the watch framebuffer. Also hosts the
+ * Node mock path used for unit tests and local development.
+ *
+ * Platform detection is via `typeof screen`:
+ *   - screen exists → Alloy/XS runtime → real Poco draws
+ *   - screen undefined → Node → mock Poco records calls to an in-memory log
+ */
+
+import { options } from 'preact';
+import type { ComponentChild } from 'preact';
+import type Poco from 'commodetto/Poco';
+import type { PocoBitmap, PocoColor, PocoFont } from 'commodetto/Poco';
+import type { DOMElement } from './pebble-dom.js';
+import { PocoRenderer } from './pebble-output.js';
+import type { PebbleButton, PebbleButtonHandler } from './hooks/index.js';
+import { ButtonRegistry } from './hooks/index.js';
+import type { PebbleContainer } from './pebble-reconciler.js';
+import {
+  createContainer,
+  updateContainer,
+  unmountContainer,
+} from './pebble-reconciler.js';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface PebblePlatformInfo {
+  isReal: boolean;
+  platform: 'alloy' | 'mock';
+  screenWidth: number;
+  screenHeight: number;
+}
+
+export interface DrawCall {
+  op: string;
+  [key: string]: unknown;
+}
+
+export interface RenderOptions {
+  backgroundColor?: string;
+}
+
+export interface PebbleApp {
+  update(newElement: ComponentChild): void;
+  unmount(): void;
+  readonly platform: PebblePlatformInfo;
+  readonly drawLog: readonly DrawCall[];
+  readonly _root: DOMElement;
+}
+
+// ---------------------------------------------------------------------------
+// Mock Poco — records every draw call into a shared log so tests can assert.
+// ---------------------------------------------------------------------------
+
+class MockPoco {
+  readonly width: number;
+  readonly height: number;
+  readonly Font: new (name: string, size: number) => PocoFont;
+
+  constructor(width: number, height: number, private readonly log: DrawCall[]) {
+    this.width = width;
+    this.height = height;
+    const FontImpl = class {
+      readonly name: string;
+      readonly size: number;
+      readonly height: number;
+      constructor(name: string, size: number) {
+        this.name = name;
+        this.size = size;
+        this.height = size;
+      }
+    };
+    this.Font = FontImpl as unknown as new (name: string, size: number) => PocoFont;
+  }
+
+  begin(x?: number, y?: number, width?: number, height?: number): void {
+    this.log.push({ op: 'begin', x, y, width, height });
+  }
+  end(): void {
+    this.log.push({ op: 'end' });
+  }
+  continue(x: number, y: number, width: number, height: number): void {
+    this.log.push({ op: 'continue', x, y, width, height });
+  }
+  clip(x?: number, y?: number, width?: number, height?: number): void {
+    this.log.push({ op: 'clip', x, y, width, height });
+  }
+  origin(x?: number, y?: number): void {
+    this.log.push({ op: 'origin', x, y });
+  }
+
+  makeColor(r: number, g: number, b: number): PocoColor {
+    return ((r & 0xff) << 16) | ((g & 0xff) << 8) | (b & 0xff);
+  }
+
+  fillRectangle(color: PocoColor, x: number, y: number, width: number, height: number): void {
+    this.log.push({ op: 'fillRectangle', color, x, y, width, height });
+  }
+  blendRectangle(
+    color: PocoColor,
+    blend: number,
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+  ): void {
+    this.log.push({ op: 'blendRectangle', color, blend, x, y, width, height });
+  }
+  drawPixel(color: PocoColor, x: number, y: number): void {
+    this.log.push({ op: 'drawPixel', color, x, y });
+  }
+  drawBitmap(_bits: PocoBitmap, x: number, y: number): void {
+    this.log.push({ op: 'drawBitmap', x, y });
+  }
+  drawMonochrome(
+    _monochrome: PocoBitmap,
+    fore: PocoColor,
+    back: PocoColor | undefined,
+    x: number,
+    y: number,
+  ): void {
+    this.log.push({ op: 'drawMonochrome', fore, back, x, y });
+  }
+
+  drawText(text: string, font: PocoFont, color: PocoColor, x: number, y: number): void {
+    this.log.push({ op: 'drawText', text, font, color, x, y });
+  }
+  getTextWidth(text: string, font: PocoFont): number {
+    const size = (font as unknown as { size?: number }).size ?? 14;
+    return Math.round(text.length * size * 0.6);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Poco construction — real on Alloy, mock in Node
+// ---------------------------------------------------------------------------
+
+function createPoco(
+  log: DrawCall[],
+  pocoCtor: typeof Poco | undefined,
+): { poco: Poco; info: PebblePlatformInfo } {
+  if (typeof screen !== 'undefined' && screen && pocoCtor) {
+    const poco = new pocoCtor(screen);
+    return {
+      poco,
+      info: {
+        isReal: true,
+        platform: 'alloy',
+        screenWidth: screen.width,
+        screenHeight: screen.height,
+      },
+    };
+  }
+
+  const width = 200;
+  const height = 228;
+  const mock = new MockPoco(width, height, log);
+  return {
+    poco: mock as unknown as Poco,
+    info: {
+      isReal: false,
+      platform: 'mock',
+      screenWidth: width,
+      screenHeight: height,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Button wiring — see moddable.d.ts for the known/unknown event names.
+// ---------------------------------------------------------------------------
+
+function wireWatchButtons(): () => void {
+  if (typeof watch === 'undefined' || !watch) return () => undefined;
+
+  const normalize = (raw: unknown): PebbleButton | undefined => {
+    if (typeof raw !== 'string') return undefined;
+    const low = raw.toLowerCase();
+    if (low === 'up' || low === 'down' || low === 'select' || low === 'back') {
+      return low;
+    }
+    return undefined;
+  };
+
+  const onShort = (payload?: { button?: unknown }) => {
+    const b = normalize(payload?.button);
+    if (b) ButtonRegistry.emit(b);
+  };
+  const onLong = (payload?: { button?: unknown }) => {
+    const b = normalize(payload?.button);
+    if (b) ButtonRegistry.emit(`long_${b}`);
+  };
+
+  watch.addEventListener('button', onShort);
+  watch.addEventListener('buttonClick', onShort);
+  watch.addEventListener('longClick', onLong);
+
+  return () => {
+    if (typeof watch === 'undefined' || !watch) return;
+    watch.removeEventListener('button', onShort);
+    watch.removeEventListener('buttonClick', onShort);
+    watch.removeEventListener('longClick', onLong);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Redraw scheduling
+//
+// Preact renders are synchronous; when any component calls setState, Preact
+// re-runs the diff and mutates the shim tree in place. We hook into that
+// by scheduling a Poco redraw on the next tick.
+// ---------------------------------------------------------------------------
+
+function scheduleMicrotask(fn: () => void): void {
+  // Prefer Promise.resolve().then for microtask batching; fall back to
+  // setTimeout(0) if Promise isn't wired up in some host.
+  if (typeof Promise !== 'undefined') {
+    Promise.resolve().then(fn);
+  } else {
+    setTimeout(fn, 0);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public render API
+// ---------------------------------------------------------------------------
+
+export interface RenderOptionsExt extends RenderOptions {
+  /**
+   * Pre-imported Poco constructor. Alloy entry files must import Poco at
+   * the top and pass it here so the Moddable bundler resolves it correctly.
+   */
+  poco?: typeof Poco;
+}
+
+export function render(element: ComponentChild, options: RenderOptionsExt = {}): PebbleApp {
+  const drawLog: DrawCall[] = [];
+  const container: PebbleContainer = createContainer();
+  const { poco, info } = createPoco(drawLog, options.poco);
+  const renderer = new PocoRenderer(poco);
+
+  let pending = false;
+  const redraw = () => {
+    pending = false;
+    drawLog.length = 0;
+    renderer.render(container.pblRoot, { backgroundColor: options.backgroundColor });
+  };
+
+  const schedule = () => {
+    if (pending) return;
+    pending = true;
+    scheduleMicrotask(redraw);
+  };
+
+  // Monkey-patch the shim root to redraw on any mutation.
+  // Preact calls appendChild/insertBefore/removeChild/setAttribute on the
+  // tree during diff; we only need to schedule a redraw when the diff
+  // settles, which is right after the top-level render() call returns.
+  // For that we just trigger a redraw synchronously after updateContainer.
+
+  // Hook Preact's commit phase so hook-driven state updates trigger a redraw
+  // without polling. options._commit is an undocumented-but-stable hook that
+  // fires once per root-level diff settle.
+  type PreactOptionsWithCommit = typeof options & {
+    _commit?: (root: unknown, queue: unknown[]) => void;
+    __c?: (root: unknown, queue: unknown[]) => void;
+  };
+  const opts = options as PreactOptionsWithCommit;
+  const prevCommit = opts._commit ?? opts.__c;
+  const commitHook = (root: unknown, queue: unknown[]) => {
+    if (prevCommit) prevCommit(root, queue);
+    schedule();
+  };
+  opts._commit = commitHook;
+  opts.__c = commitHook;
+
+  updateContainer(element, container);
+  // Always paint once on mount.
+  redraw();
+
+  // Subscribe to watch events on-device.
+  const unwireButtons = wireWatchButtons();
+
+  return {
+    update(newElement) {
+      updateContainer(newElement, container);
+      schedule();
+    },
+    unmount() {
+      unmountContainer(container);
+      // Restore prior commit hook (in case another app was rendered).
+      opts._commit = prevCommit;
+      opts.__c = prevCommit;
+      unwireButtons();
+    },
+    get platform() {
+      return info;
+    },
+    get drawLog() {
+      return drawLog as readonly DrawCall[];
+    },
+    get _root() {
+      return container.pblRoot;
+    },
+  };
+}

package/src/platform.ts

@@ -0,0 +1,50 @@
+/**
+ * src/platform.ts — Screen dimensions and platform constants.
+ *
+ * The compiler sets these before rendering so components can use
+ * SCREEN.width / SCREEN.height instead of hardcoding pixel values.
+ *
+ * Usage:
+ *   import { SCREEN } from 'react-pebble';
+ *   <Rect x={0} y={0} w={SCREEN.width} h={SCREEN.height} fill="black" />
+ */
+
+export interface PebblePlatform {
+  name: string;
+  width: number;
+  height: number;
+  isRound: boolean;
+}
+
+export const PLATFORMS: Record<string, PebblePlatform> = {
+  emery: { name: 'emery', width: 200, height: 228, isRound: false },
+  gabbro: { name: 'gabbro', width: 200, height: 228, isRound: false },
+  // These are NOT supported by Alloy, but listed for reference/future Rocky.js:
+  basalt: { name: 'basalt', width: 144, height: 168, isRound: false },
+  chalk: { name: 'chalk', width: 180, height: 180, isRound: true },
+  diorite: { name: 'diorite', width: 144, height: 168, isRound: false },
+  aplite: { name: 'aplite', width: 144, height: 168, isRound: false },
+};
+
+/**
+ * Current screen dimensions. Set by the compiler before rendering.
+ * Components import this and use SCREEN.width / SCREEN.height for
+ * responsive layouts.
+ */
+export const SCREEN = {
+  width: 200,
+  height: 228,
+  isRound: false,
+  platform: 'emery',
+};
+
+/** @internal — called by the compiler to set the platform. */
+export function _setPlatform(platform: string): void {
+  const p = PLATFORMS[platform];
+  if (p) {
+    SCREEN.width = p.width;
+    SCREEN.height = p.height;
+    SCREEN.isRound = p.isRound;
+    SCREEN.platform = p.name;
+  }
+}

package/src/plugin/index.ts

@@ -0,0 +1,274 @@
+/**
+ * src/plugin/index.ts — Vite plugin for react-pebble.
+ *
+ * Compiles JSX components to piu, scaffolds the Pebble project, and
+ * optionally builds + deploys to the emulator. Users add this to their
+ * vite.config.ts and run `vite build`.
+ *
+ * Usage:
+ *   import { pebblePiu } from 'react-pebble/plugin';
+ *
+ *   export default defineConfig({
+ *     plugins: [
+ *       pebblePiu({
+ *         entry: 'src/App.tsx',
+ *         settleMs: 200,
+ *         deploy: true,
+ *       }),
+ *     ],
+ *   });
+ */
+
+import type { Plugin } from 'vite';
+import { execSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { compileToPiu } from '../compiler/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export interface PebblePiuOptions {
+  /** Path to the entry .tsx file (relative to project root) */
+  entry: string;
+  /** Milliseconds to wait for async effects before snapshotting */
+  settleMs?: number;
+  /** Target platform — sets screen dimensions (default: 'emery') */
+  platform?: string;
+  /** Directory for the generated Pebble project (default: '.pebble-build') */
+  buildDir?: string;
+  /** Auto-run pebble build + install after compilation */
+  deploy?: boolean;
+  /** Emulator platform for deploy (default: same as platform) */
+  emulator?: string;
+}
+
+/**
+ * Vite plugin that compiles react-pebble JSX to piu and scaffolds a
+ * Pebble project for deployment.
+ */
+export function pebblePiu(options: PebblePiuOptions): Plugin {
+  const buildDir = resolve(options.buildDir ?? '.pebble-build');
+
+  return {
+    name: 'react-pebble-piu',
+    apply: 'build',
+
+    async closeBundle() {
+      const log = (msg: string) => console.log(`[react-pebble] ${msg}`);
+
+      // 1. Compile JSX → piu
+      log(`Compiling ${options.entry}...`);
+      const result = await compileToPiu({
+        entry: options.entry,
+        settleMs: options.settleMs,
+        platform: options.platform,
+        logger: log,
+      });
+
+      // 2. Scaffold pebble project
+      log(`Scaffolding pebble project in ${buildDir}...`);
+      scaffoldPebbleProject(buildDir, {
+        watchface: !result.hasButtons,
+        messageKeys: result.messageKeys,
+      });
+
+      // 3. Write compiled output
+      const outputPath = join(buildDir, 'src', 'embeddedjs', 'main.js');
+      mkdirSync(dirname(outputPath), { recursive: true });
+      writeFileSync(outputPath, result.code);
+      log(`Wrote ${result.code.split('\n').length} lines to ${outputPath}`);
+
+      // 4. Optionally build + deploy
+      if (options.deploy) {
+        const emu = options.emulator ?? options.platform ?? 'emery';
+        log('Running pebble build...');
+        try {
+          execSync('pebble build', { cwd: buildDir, stdio: 'inherit' });
+          log(`Installing to ${emu} emulator...`);
+          execSync('pebble kill 2>/dev/null; pebble wipe 2>/dev/null; sleep 2', {
+            cwd: buildDir,
+            stdio: 'ignore',
+          });
+        execSync(`pebble install --emulator ${emu}`, {
+            cwd: buildDir,
+            stdio: 'inherit',
+            timeout: 30000,
+          });
+          log(`Deployed to ${emu}. Run 'cd ${buildDir} && pebble logs' for live output.`);
+        } catch (err) {
+          log('Deploy failed — is the Pebble SDK installed? (pebble --version)');
+          throw err;
+        }
+      } else {
+        log(`Done. To deploy:\n  cd ${buildDir} && pebble build && pebble install --emulator emery`);
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pebble project scaffolding
+// ---------------------------------------------------------------------------
+
+interface ScaffoldOptions {
+  watchface: boolean;
+  messageKeys: string[];
+}
+
+function scaffoldPebbleProject(dir: string, options: ScaffoldOptions): void {
+  mkdirSync(join(dir, 'src', 'embeddedjs'), { recursive: true });
+  mkdirSync(join(dir, 'src', 'c'), { recursive: true });
+  mkdirSync(join(dir, 'src', 'pkjs'), { recursive: true });
+
+  // Preserve UUID across builds (or generate a new one)
+  let uuid: string;
+  const pkgPath = join(dir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const existing = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      uuid = existing?.pebble?.uuid ?? randomUUID();
+    } catch {
+      uuid = randomUUID();
+    }
+  } else {
+    uuid = randomUUID();
+  }
+
+  // package.json
+  const pkg = {
+    name: 'react-pebble-app',
+    author: 'react-pebble',
+    version: '1.0.0',
+    keywords: ['pebble-app'],
+    private: true,
+    dependencies: {},
+    pebble: {
+      displayName: 'react-pebble-app',
+      uuid,
+      projectType: 'moddable',
+      sdkVersion: '3',
+      enableMultiJS: true,
+      targetPlatforms: ['emery', 'gabbro'],
+      watchapp: { watchface: options.watchface },
+      messageKeys: options.messageKeys.length > 0 ? options.messageKeys : ['dummy'],
+      resources: { media: [] },
+    },
+  };
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+
+  // wscript (static — Pebble SDK build config)
+  const wscriptPath = join(dir, 'wscript');
+  if (!existsSync(wscriptPath)) {
+    writeFileSync(wscriptPath, WSCRIPT_TEMPLATE);
+  }
+
+  // C stub (static)
+  const cPath = join(dir, 'src', 'c', 'mdbl.c');
+  if (!existsSync(cPath)) {
+    writeFileSync(
+      cPath,
+      `#include <pebble.h>
+
+int main(void) {
+  Window *w = window_create();
+  window_stack_push(w, true);
+
+  moddable_createMachine(NULL);
+
+  window_destroy(w);
+}
+`,
+    );
+  }
+
+  // Moddable manifest (static)
+  const manifestPath = join(dir, 'src', 'embeddedjs', 'manifest.json');
+  if (!existsSync(manifestPath)) {
+    writeFileSync(
+      manifestPath,
+      JSON.stringify(
+        {
+          include: ['$(MODDABLE)/examples/manifest_mod.json'],
+          modules: { '*': './main.js' },
+        },
+        null,
+        2,
+      ) + '\n',
+    );
+  }
+
+  // Phone-side JS
+  const pkjsPath = join(dir, 'src', 'pkjs', 'index.js');
+  if (options.messageKeys.length > 0 && options.messageKeys[0] !== 'dummy') {
+    writeFileSync(
+      pkjsPath,
+      `// Phone-side PebbleKit JS — sends data to watch via AppMessage.
+// Replace the mock data below with a real API fetch.
+
+Pebble.addEventListener("ready", function () {
+  console.log("Phone JS ready.");
+  // TODO: fetch real data and send via Pebble.sendAppMessage({ ${options.messageKeys[0]}: jsonString });
+});
+`,
+    );
+  } else if (!existsSync(pkjsPath)) {
+    writeFileSync(
+      pkjsPath,
+      `Pebble.addEventListener("ready", function(e) {
+  console.log("PebbleKit JS ready.");
+});
+`,
+    );
+  }
+}
+
+// Named export only — avoids Vite's MIXED_EXPORTS warning.
+// Users import as: import { pebblePiu } from 'react-pebble/plugin';
+
+// ---------------------------------------------------------------------------
+// Inline templates (no external file dependencies)
+// ---------------------------------------------------------------------------
+
+const WSCRIPT_TEMPLATE = `#
+# Pebble SDK build configuration (auto-generated by react-pebble plugin)
+#
+import os.path
+
+top = '.'
+out = 'build'
+
+def options(ctx):
+    ctx.load('pebble_sdk')
+
+def configure(ctx):
+    ctx.load('pebble_sdk')
+
+def build(ctx):
+    ctx.load('pebble_sdk')
+    build_worker = os.path.exists('worker_src')
+    binaries = []
+    cached_env = ctx.env
+    for platform in ctx.env.TARGET_PLATFORMS:
+        ctx.env = ctx.all_envs[platform]
+        ctx.set_group(ctx.env.PLATFORM_NAME)
+        app_elf = '{}/pebble-app.elf'.format(ctx.env.BUILD_DIR)
+        ctx.pbl_build(source=ctx.path.ant_glob('src/c/**/*.c'), target=app_elf, bin_type='app')
+        if build_worker:
+            worker_elf = '{}/pebble-worker.elf'.format(ctx.env.BUILD_DIR)
+            binaries.append({'platform': platform, 'app_elf': app_elf, 'worker_elf': worker_elf})
+            ctx.pbl_build(source=ctx.path.ant_glob('worker_src/c/**/*.c'), target=worker_elf, bin_type='worker')
+        else:
+            binaries.append({'platform': platform, 'app_elf': app_elf})
+    ctx.env = cached_env
+    ctx.set_group('bundle')
+    ctx.pbl_bundle(binaries=binaries,
+                   js=ctx.path.ant_glob(['src/pkjs/**/*.js', 'src/pkjs/**/*.json', 'src/common/**/*.js']),
+                   js_entry_file='src/pkjs/index.js')
+`;