@geastack/core 0.1.23

package/runtime/images.ts

@@ -0,0 +1,129 @@
+import type { GeaEmbeddedImage } from '../index'
+
+export type LoadImageOptions = {
+  opaque?: boolean
+}
+
+declare const image: {
+  loadBytes(bytes: Uint8Array): number
+  loadBytesOpaque(bytes: Uint8Array): number
+  // Read + decode an image directly from a persistent-cache file (e.g. microSD).
+  // Returns a slot id, or -1 when the file is missing/undecodable.
+  loadFile(path: string): number
+  loadFileOpaque(path: string): number
+  // Decode a BUILD-EMBEDDED asset by its path relative to the app directory
+  // (e.g. 'assets/icons/00-music.png'). Returns a slot id, or -1 when no such
+  // asset was bundled.
+  loadAssetPath(path: string): number
+  // Save raw bytes to a persistent-cache file (creating parent dirs). Returns
+  // true on success, false when no persistent storage is available.
+  writeFile(path: string, bytes: Uint8Array): boolean
+  // Read a whole file's raw bytes (e.g. a .pmtiles on microSD). Empty when the
+  // file is missing or no storage is mounted.
+  readFile(path: string): Uint8Array
+  // Read a .pmtiles archive flashed into the spare ota_1 partition. Empty when
+  // none present (or off-device).
+  readMapArchive(): Uint8Array
+  // Read a byte range [offset, offset+length) from a file without loading it
+  // all. Empty when absent / no storage.
+  readFileRange(path: string, offset: number, length: number): Uint8Array
+  // List a directory's regular-file names (non-recursive), newline-joined.
+  // Empty string when the directory is missing or no storage is mounted.
+  listFiles(path: string): string
+  // Synchronous HTTP GET over WiFi.
+  fetchBytes(url: string): Uint8Array
+  fetchText(url: string): string
+  // Wrap a decoded slot id in the native `GeaEmbeddedImage` handle, snapshotting
+  // its immutable dimensions. Lowering this through the host keeps the returned
+  // value a concrete struct (no boxed record), so callers and any
+  // `GeaEmbeddedImage[]` cache stay fully typed.
+  make(id: number): GeaEmbeddedImage
+}
+
+export function loadImage(src: Uint8Array, options?: LoadImageOptions): GeaEmbeddedImage {
+  const opaque = options ? options.opaque || false : false
+  return loadImageWithOpaque(src, opaque)
+}
+
+// Scalar fast path for embedded callers whose opacity is already known. This
+// keeps the hot image decode call native without constructing an options
+// record at the C++ boundary.
+export function loadImageWithOpaque(src: Uint8Array, opaque: boolean): GeaEmbeddedImage {
+  const id = opaque ? image.loadBytesOpaque(src) : image.loadBytes(src)
+  return image.make(id)
+}
+
+// Load + decode an image from a persistent-cache file path (e.g. an SD-card tile
+// cache). The returned handle has width === 0 when the file is absent or fails
+// to decode, so callers treat that as a cache miss and fetch over the network.
+export function loadImageFile(path: string, options?: LoadImageOptions): GeaEmbeddedImage {
+  const opaque = options ? options.opaque || false : false
+  const id = opaque ? image.loadFileOpaque(path) : image.loadFile(path)
+  return image.make(id)
+}
+
+// Load + decode a BUILD-EMBEDDED asset by its path relative to the app
+// directory (e.g. 'assets/icons/00-music.png'), the same bytes `<img src>`
+// would use. The JSX path lowers a string LITERAL straight to the generated
+// `gea_asset_<path>` symbol, which is unavailable to a canvas app that picks
+// among N bundled images at runtime -- this resolves the path through the
+// generated lookup table instead. Decoding is deferred to first draw and
+// memoized per asset, so calling it repeatedly for the same path is free.
+// The returned handle has `width === 0` when no such asset was bundled.
+export function loadAssetImage(path: string): GeaEmbeddedImage {
+  // Two statements, not a nested call: the host-object lowering only qualifies
+  // the OUTERMOST `image.<method>` receiver, so `image.make(image.loadX(...))`
+  // emits an unqualified inner `image` and fails to compile.
+  const id = image.loadAssetPath(path)
+  return image.make(id)
+}
+
+// Persist raw bytes to the file cache (e.g. /sdcard/...). Returns false when no
+// writable storage is mounted, so callers can ignore the result.
+export function writeCacheFile(path: string, bytes: Uint8Array): boolean {
+  return image.writeFile(path, bytes)
+}
+
+// Read a whole file's raw bytes from the persistent cache (e.g. a .pmtiles
+// pushed to /sdcard). Returns an empty Uint8Array when absent / no storage.
+export function readCacheFile(path: string): Uint8Array {
+  return image.readFile(path)
+}
+
+// Read a .pmtiles archive flashed into the spare ota_1 partition over USB
+// (esptool) — a reliable data path independent of the SD card. Empty when none.
+export function readMapArchive(): Uint8Array {
+  return image.readMapArchive()
+}
+
+// Read a byte range from a persistent-cache file (e.g. one tile out of a
+// .pmtiles on microSD) without loading the whole file.
+export function readFileRange(path: string, offset: number, length: number): Uint8Array {
+  return image.readFileRange(path, offset, length)
+}
+
+// List a directory's regular-file names (non-recursive) from persistent storage
+// (e.g. the EPUBs in /sdcard/books). Empty array when the directory is missing
+// or no storage is mounted.
+export function listCacheFiles(path: string): string[] {
+  const joined = image.listFiles(path)
+  if (joined.length == 0) return []
+  return joined.split('\n')
+}
+
+// Synchronous HTTP GET over WiFi — body as bytes (e.g. an MVT tile) or text
+// (e.g. a TileJSON). Empty when WiFi is down / the request fails.
+export function fetchBytes(url: string): Uint8Array {
+  return image.fetchBytes(url)
+}
+
+export function fetchText(url: string): string {
+  return image.fetchText(url)
+}
+
+// Wrap an already-decoded image-store slot id (e.g. one delivered by the async
+// tile loader) in the native GeaEmbeddedImage handle. width === 0 when the id
+// is invalid.
+export function imageFromId(id: number): GeaEmbeddedImage {
+  return image.make(id)
+}

package/runtime/primitives.ts

@@ -0,0 +1,49 @@
+import { Component } from './compiler'
+
+/**
+ * Whatever the `document` in scope hands back for an id, minus the miss.
+ *
+ * Not a named element type. This file is compiled under two different worlds:
+ * a project that includes lib.dom (`document` is lib.dom's, answering
+ * `HTMLElement`) and one that does not (`document` is the framework's,
+ * answering the framework's `Element`). Naming either one is wrong under the
+ * other, and naming `HTMLElement` in particular made the DOM library a build
+ * requirement of every pipeline that compiles this file.
+ */
+type MountRoot = NonNullable<ReturnType<typeof document.getElementById>>
+// Typed as a component constructor — no `any`. geatsc lowers a `new () => T`
+// parameter to an abbreviated-template forwarding reference, so this function is
+// instantiated per call site and `new component()` constructs the concrete app
+// class natively (no boxing, no dynamic construct path).
+//
+// The parameter is named `component`, NOT `App`: geatsc emits user classes into
+// flat global C++ scope, so a parameter named after a common root class would
+// shadow it at this construction site.
+export function mount<RootComponent extends Component>(component: new () => RootComponent): void {
+  const root = document.getElementById('app')
+  if (!root) throw new Error('gea-embedded mount root #app was not found')
+  const instance = new component()
+  // `render` is synthesised onto compiled components and is not on the base
+  // `Component` type (see compiler.ts for why it must not be), so reach it
+  // through a local structural cast rather than widening the parameter to `any`.
+  //
+  // The cast goes through `unknown` because the two types genuinely do not
+  // overlap: the base declares no `render` at all, so a direct assertion is one
+  // TypeScript rightly rejects. It was only ever accepted while this file went
+  // unchecked -- a pipeline resolving `@geastack/core` to `index.d.ts` never
+  // compiles it.
+  //
+  // The parameter is spelled off `root` itself rather than by name. It used to
+  // read `HTMLElement` -- a lib.dom global this framework never declares -- and
+  // that one word made the DOM library a build requirement of every pipeline
+  // that compiles this file, which then merged lib.dom's `Window`/`globalThis`
+  // into apps that had declared their own. Naming the framework's `Element`
+  // instead is no better in the other direction: under a project that DOES
+  // include lib.dom, `document` is lib.dom's and its `getElementById` answers
+  // `HTMLElement`, which is not assignable to it. `typeof root` is neither: it
+  // is whatever `document` in scope actually answers, which is the only correct
+  // answer in both. Read off the METHOD rather than off `root`: `typeof root`
+  // inside this assertion really is circular, because narrowing makes `root`'s
+  // type here depend on the assertion being resolved first.
+  ;(instance as unknown as { render(root: MountRoot, depth: number): void }).render(root, 1)
+}

package/runtime-surface.ts

@@ -0,0 +1,180 @@
+export * from './runtime/compiler'
+export * from './runtime/host'
+export * from './runtime/ble'
+export * from './runtime/images'
+export * from './runtime/color'
+export { mount } from './runtime/primitives'
+// The embedded/geatsc pipeline aliases '@geastack/core' to runtime.ts, so an
+// app's `import type { GeaCanvasElement, GeaEmbeddedImage } from
+// '@geastack/core'` resolves HERE, not through the package's index.d.ts.
+// Without these re-exports those names silently fail to resolve, the checker
+// types the annotated binding `any`, and geatsc lowers it to a boxed
+// `gea_cpp_value` instead of the typed native handle (NodeHandle /
+// gea::host::GeaEmbeddedImage) the annotation exists to pin.
+export type {
+  GeaNode,
+  GeaElement,
+  GeaCanvasElement,
+  GeaCameraElement,
+  GeaEmbeddedImage,
+  FetchResponse,
+  TouchSample,
+  // Also a lib.dom global. An app annotating a context `CanvasRenderingContext2D`
+  // and resolving it here got the DOM one (or nothing), not the framework's --
+  // which declares the whole embedded surface (`fillCirclesRgb565`, `flush`,
+  // `beginBatch`) that the DOM interface has never heard of.
+  CanvasRenderingContext2D,
+  Element,
+} from './index'
+
+/**
+ * Every remaining type `index.d.ts` publishes, re-exported so the name an app
+ * imports resolves whichever file the specifier landed on.
+ *
+ * The package answers `"."` with two files -- `types: ./index.d.ts` for an
+ * editor, `default: ./runtime.ts` (which is this module) for anything that
+ * compiles the framework from source. A name declared only in the first is a
+ * name the second does not have, and an app that imports it there gets
+ * `Module '"@geastack/core"' has no exported member 'X'` -- after which the
+ * checker types the annotated binding `any` and a compiler lowers it to a
+ * boxed dynamic value instead of the native handle the annotation exists to
+ * pin. `VirtualListElement` cost `examples/virtual-list` 25 boxed values
+ * exactly that way.
+ *
+ * The block above states the names whose resolution was already known to
+ * matter, with the reasoning for each; this states the rest, derived by
+ * DIFFERENCE rather than by hand -- every type-only export of `index.d.ts`
+ * that this surface did not already carry. Adding them one at a time as each
+ * app trips over one is how the gap appeared in the first place.
+ *
+ * Type-only, deliberately. `index.d.ts` also declares values (`fetchAsync`
+ * and its siblings, the two brand constants) that nothing here defines;
+ * re-exporting one of those would make a program that calls it compile and
+ * then fail to link, which is worse than the honest "no exported member" it
+ * gets today.
+ */
+export type {
+  AccelerometerController,
+  AccelerometerReading,
+  AppsController,
+  AudioBuffer,
+  AudioBufferSourceNode,
+  AudioConstructor,
+  AudioContext,
+  AudioContextConstructor,
+  AudioController,
+  AudioDestinationNode,
+  AudioParam,
+  AudioProps,
+  BatteryController,
+  BluetoothConfig,
+  BluetoothConnections,
+  BluetoothController,
+  BluetoothHidHost,
+  BluetoothKeyboard,
+  BluetoothMidi,
+  BluetoothMouse,
+  ButtonProps,
+  CameraController,
+  CameraProps,
+  CanvasProps,
+  ClassMap,
+  ClassValue,
+  ClockController,
+  DOMTokenList,
+  DataAttributes,
+  DeviceControlController,
+  DisplayController,
+  DisplayEpaperRefreshConfig,
+  DisplayFlushConfig,
+  DisplayMemoryConfig,
+  DisplayOrientation,
+  DisplayOrientationSupport,
+  DisplayPixelFormat,
+  Document,
+  EmbeddedDefaults,
+  Event,
+  EventTarget,
+  FetchHeaders,
+  FetchHeadersInit,
+  FetchRequestInit,
+  GeaAudioBlob,
+  GeaEventMap,
+  GeaJsxElement,
+  GeaJsxElementChildrenAttribute,
+  GeaLocalStorage,
+  GeaWindow,
+  GeolocationController,
+  GeolocationCoordinates,
+  GeolocationPosition,
+  GeolocationPositionError,
+  HTMLAudioElement,
+  HttpModule,
+  HttpRequestHandler,
+  HttpServer,
+  ImageProps,
+  ImageSource,
+  IncomingMessage,
+  InputController,
+  InputElementProps,
+  InputEvent,
+  InputEventTarget,
+  KeyEvent,
+  MediaDevices,
+  MediaRecorder,
+  MediaRecorderConstructor,
+  MediaRecorderDataAvailableEvent,
+  MediaRecorderOptions,
+  MediaRecorderState,
+  MediaStream,
+  MediaStreamConstraints,
+  MediaStreamConstructor,
+  MediaStreamTrack,
+  MemoryController,
+  NativeButtonProps,
+  NativeEventAttributes,
+  NativeInputElementProps,
+  NativeTextAreaElementProps,
+  NativeTouchEventAttributes,
+  NativeViewProps,
+  NativeVirtualListProps,
+  Node,
+  NotifyController,
+  OscillatorNode,
+  OscillatorType,
+  PointerEvent,
+  PositionOptions,
+  PressEvent,
+  PressEventArgument,
+  PressEventTarget,
+  PressHandler,
+  ProfilerController,
+  RTCConfiguration,
+  RTCIceCandidateInit,
+  RTCIceServer,
+  RTCPeerConnectionConstructor,
+  RTCPeerConnectionIceEvent,
+  RTCPeerConnectionInstance,
+  RTCSessionDescriptionInit,
+  RTCTrackEvent,
+  RotaryEvent,
+  RotaryEventHandler,
+  ScrollIntoViewOptions,
+  Style,
+  StyleBox,
+  StyleLength,
+  TextAreaElementProps,
+  TextProps,
+  TouchEvent,
+  TouchEventHandler,
+  TouchHost,
+  TouchPoint,
+  ViewProps,
+  VirtualListElement,
+  WebSocketCloseEvent,
+  WebSocketConstructor,
+  WebSocketErrorEvent,
+  WebSocketInstance,
+  WebSocketMessageEvent,
+  WiFiController,
+} from './index'