@galfus/engine 0.0.0-stage → 0.31.0-alpha

package/src/spatial/dirty_registry.ts

@@ -0,0 +1,217 @@
+/**
+ * DirtyRegistry manages mutations, dirty revision tracking, and transaction coalescence.
+ * Prevents redundant ABI uploads and cancels create+destroy cycles within uncommitted frames.
+ */
+
+export type DirtyOp = 'create' | 'update' | 'destroy';
+
+export interface DirtyRecord<T = unknown> {
+  readonly scopeId: number;
+  readonly objectKey: number | string;
+  op: DirtyOp;
+  currentRevision: number;
+  uploadedRevision: number;
+  payload?: T;
+  /** Indicates that the object has never been successfully confirmed to core yet. */
+  isNew: boolean;
+}
+
+export class DirtyRegistry<T = unknown> {
+  private readonly _records = new Map<string, DirtyRecord<T>>();
+
+  private _makeKey(scopeId: number, objectKey: number | string): string {
+    return `${scopeId}:${objectKey}`;
+  }
+
+  /** Total number of tracked records in the registry. */
+  get size(): number {
+    return this._records.size;
+  }
+
+  /** Number of records currently needing upload to core. */
+  get pendingCount(): number {
+    let count = 0;
+    for (const record of this._records.values()) {
+      if (record.currentRevision > record.uploadedRevision) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Registers a new object creation in this scope.
+   */
+  recordCreate(scopeId: number, objectKey: number | string, payload?: T): DirtyRecord<T> {
+    const key = this._makeKey(scopeId, objectKey);
+    const existing = this._records.get(key);
+
+    if (existing) {
+      if (existing.op === 'destroy') {
+        existing.op = existing.uploadedRevision > 0 ? 'update' : 'create';
+      }
+      existing.currentRevision++;
+      if (payload !== undefined) {
+        existing.payload = payload;
+      }
+      return existing;
+    }
+
+    const record: DirtyRecord<T> = {
+      scopeId,
+      objectKey,
+      op: 'create',
+      currentRevision: 1,
+      uploadedRevision: 0,
+      payload,
+      isNew: true
+    };
+    this._records.set(key, record);
+    return record;
+  }
+
+  /**
+   * Records a mutation on an object, incrementing its revision.
+   */
+  recordMutation(scopeId: number, objectKey: number | string, payload?: T): DirtyRecord<T> {
+    const key = this._makeKey(scopeId, objectKey);
+    const existing = this._records.get(key);
+
+    if (existing) {
+      existing.currentRevision++;
+      if (payload !== undefined) {
+        existing.payload = payload;
+      }
+      return existing;
+    }
+
+    // Object was already known to core prior to tracking
+    const record: DirtyRecord<T> = {
+      scopeId,
+      objectKey,
+      op: 'update',
+      currentRevision: 1,
+      uploadedRevision: 0,
+      payload,
+      isNew: false
+    };
+    this._records.set(key, record);
+    return record;
+  }
+
+  /**
+   * Records an object destruction.
+   * If the object was created and destroyed prior to any core upload,
+   * it is completely coalesced and removed from the registry (0 ABI calls).
+   *
+   * @returns `true` if a core destroy call is pending; `false` if coalesced to zero.
+   */
+  recordDestroy(scopeId: number, objectKey: number | string): boolean {
+    const key = this._makeKey(scopeId, objectKey);
+    const existing = this._records.get(key);
+
+    if (existing) {
+      // Coalescence rule: created and destroyed before first upload
+      if (existing.isNew && existing.uploadedRevision === 0) {
+        this._records.delete(key);
+        return false;
+      }
+
+      existing.op = 'destroy';
+      existing.currentRevision++;
+      existing.payload = undefined;
+      return true;
+    }
+
+    // Object was previously uploaded and tracked by core
+    const record: DirtyRecord<T> = {
+      scopeId,
+      objectKey,
+      op: 'destroy',
+      currentRevision: 1,
+      uploadedRevision: 0,
+      isNew: false
+    };
+    this._records.set(key, record);
+    return true;
+  }
+
+  /**
+   * Returns all records whose currentRevision > uploadedRevision.
+   */
+  getPendingDirty(): DirtyRecord<T>[] {
+    const pending: DirtyRecord<T>[] = [];
+    for (const record of this._records.values()) {
+      if (record.currentRevision > record.uploadedRevision) {
+        pending.push(record);
+      }
+    }
+    return pending;
+  }
+
+  /**
+   * Iterates through pending dirty records without allocating an intermediate array.
+   */
+  forEachPending(callback: (record: DirtyRecord<T>) => void): void {
+    for (const record of this._records.values()) {
+      if (record.currentRevision > record.uploadedRevision) {
+        callback(record);
+      }
+    }
+  }
+
+  /**
+   * Confirms successful synchronization of an object to the core.
+   */
+  confirmSync(scopeId: number, objectKey: number | string, revision?: number): void {
+    const key = this._makeKey(scopeId, objectKey);
+    const existing = this._records.get(key);
+    if (!existing) return;
+
+    if (existing.op === 'destroy') {
+      this._records.delete(key);
+      return;
+    }
+
+    existing.uploadedRevision = revision ?? existing.currentRevision;
+    existing.isNew = false;
+    if (existing.op === 'create') {
+      existing.op = 'update';
+    }
+  }
+
+  /**
+   * Indicates sync failed for an object, retaining its dirty status for retry on the next frame.
+   */
+  failSync(_scopeId: number, _objectKey: number | string): void {
+    // uploadedRevision is left unchanged so currentRevision > uploadedRevision persists
+  }
+
+  /**
+   * Retrieves a record by scope and object key.
+   */
+  get(scopeId: number, objectKey: number | string): DirtyRecord<T> | undefined {
+    return this._records.get(this._makeKey(scopeId, objectKey));
+  }
+
+  /**
+   * Checks whether a record is tracked.
+   */
+  has(scopeId: number, objectKey: number | string): boolean {
+    return this._records.has(this._makeKey(scopeId, objectKey));
+  }
+
+  /**
+   * Deletes a record from the registry.
+   */
+  delete(scopeId: number, objectKey: number | string): boolean {
+    return this._records.delete(this._makeKey(scopeId, objectKey));
+  }
+
+  /**
+   * Clears all records.
+   */
+  clear(): void {
+    this._records.clear();
+  }
+}

package/src/spatial/flags.ts

@@ -0,0 +1,14 @@
+/**
+ * Spatial dirty flags bitmask for 2D and 3D spatial models.
+ * Controls the two-stage lifecycle: local change -> anchor solve -> world change -> core sync.
+ */
+export const enum SpatialDirtyFlags {
+  /** Clean state: no updates needed in solver or core */
+  Clean = 0,
+  /** Local transform changed: Anchor solver needs to update worldMatrix */
+  LocalDirty = 1 << 0,
+  /** World matrix changed: Realm sync needs to upload worldMatrix to core */
+  WorldDirty = 1 << 1,
+  /** Descriptor changed: Realm sync needs to upload descriptor/material/flags to core */
+  DescDirty = 1 << 2
+}

package/src/spatial/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Spatial types, flags, and model representations for 2D and 3D scenes.
+ */
+export * from './dirty_registry';
+export * from './flags';
+export * from './metrics';

package/src/spatial/metrics.ts

@@ -0,0 +1,124 @@
+/**
+ * ABI Call Metrics Tracker for monitoring, diagnostics, and zero-ABI regression testing.
+ * Intercepts GalfusEngine calls and categorizes them.
+ */
+
+import type { GalfusEngine } from '@galfus/transport-types';
+
+export type AbiCallCategory =
+  'create' | 'updateTransform' | 'updateDescriptor' | 'destroy' | 'query' | 'dispatch' | 'other';
+
+export interface AbiMetricsSnapshot {
+  readonly total: number;
+  readonly byCategory: Record<AbiCallCategory, number>;
+  readonly byMethod: Record<string, number>;
+}
+
+function categorizeMethod(name: string): AbiCallCategory {
+  if (name.includes('Dispatch') || name.includes('PumpEvents')) {
+    return 'dispatch';
+  }
+  if (
+    name.startsWith('realm3dUpdateModelTransform') ||
+    name.startsWith('realm2dUpdate') ||
+    name.includes('Transform') ||
+    name.includes('SetPosition') ||
+    name.includes('SetRotation')
+  ) {
+    return 'updateTransform';
+  }
+  if (
+    name.includes('Update') ||
+    name.includes('Set') ||
+    name.includes('Attribute') ||
+    name.includes('Morph') ||
+    name.includes('Bones')
+  ) {
+    return 'updateDescriptor';
+  }
+  if (
+    name.includes('Create') ||
+    name.includes('Load') ||
+    name.includes('Register') ||
+    name.includes('Attach')
+  ) {
+    return 'create';
+  }
+  if (
+    name.includes('Destroy') ||
+    name.includes('Close') ||
+    name.includes('Unregister') ||
+    name.includes('Unload') ||
+    name.includes('Dispose') ||
+    name.includes('Clear')
+  ) {
+    return 'destroy';
+  }
+  if (
+    name.includes('Get') ||
+    name.includes('Has') ||
+    name.includes('Find') ||
+    name.includes('Query')
+  ) {
+    return 'query';
+  }
+  return 'other';
+}
+
+export class AbiMetricsTracker {
+  private _total = 0;
+  private readonly _byCategory: Record<AbiCallCategory, number> = {
+    create: 0,
+    updateTransform: 0,
+    updateDescriptor: 0,
+    destroy: 0,
+    query: 0,
+    dispatch: 0,
+    other: 0
+  };
+  private readonly _byMethod: Record<string, number> = {};
+
+  recordCall(methodName: string): void {
+    this._total++;
+    const cat = categorizeMethod(methodName);
+    this._byCategory[cat]++;
+    this._byMethod[methodName] = (this._byMethod[methodName] ?? 0) + 1;
+  }
+
+  reset(): void {
+    this._total = 0;
+    for (const key of Object.keys(this._byCategory) as AbiCallCategory[]) {
+      this._byCategory[key] = 0;
+    }
+    for (const key of Object.keys(this._byMethod)) {
+      delete this._byMethod[key];
+    }
+  }
+
+  getSnapshot(): AbiMetricsSnapshot {
+    return {
+      total: this._total,
+      byCategory: { ...this._byCategory },
+      byMethod: { ...this._byMethod }
+    };
+  }
+
+  /**
+   * Wraps a GalfusEngine instance with a proxy that tracks every method invocation.
+   */
+  wrapEngine(engine: GalfusEngine): GalfusEngine {
+    const tracker = this;
+    return new Proxy(engine, {
+      get(target, prop, receiver) {
+        const orig = Reflect.get(target, prop, receiver);
+        if (typeof orig === 'function') {
+          return function (...args: unknown[]) {
+            tracker.recordCall(String(prop));
+            return orig.apply(target, args);
+          };
+        }
+        return orig;
+      }
+    });
+  }
+}

package/src/text/editor.ts

@@ -0,0 +1,224 @@
+import { graphemeSegments } from 'unicode-segmenter/grapheme';
+
+/** UTF-16 offsets at grapheme boundaries. Anchor and focus preserve selection direction. */
+export interface TextSelection {
+  readonly anchor: number;
+  readonly focus: number;
+}
+
+export interface TextComposition {
+  readonly text: string;
+  /** UTF-16 offsets within the preview, when supplied by the input method. */
+  readonly selection?: readonly [number, number];
+}
+
+function charType(grapheme: string): 'space' | 'word' | 'punct' {
+  if (/^\s+$/u.test(grapheme)) return 'space';
+  if (/^[\p{L}\p{M}\p{N}_]+$/u.test(grapheme)) return 'word';
+  return 'punct';
+}
+
+/** Platform-independent text editing state. Text remains Unicode inside the host. */
+export class TextEditor {
+  private value_: string;
+  private boundaries: number[] = [];
+  private anchor_: number;
+  private focus_: number;
+  private composition_: TextComposition | undefined;
+
+  constructor(value = '') {
+    this.value_ = value;
+    this.rebuildBoundaries();
+    this.anchor_ = this.focus_ = value.length;
+  }
+
+  get value(): string {
+    return this.value_;
+  }
+
+  get selection(): TextSelection {
+    return { anchor: this.anchor_, focus: this.focus_ };
+  }
+
+  get selectedText(): string {
+    const [start, end] = this.range();
+    return this.value_.slice(start, end);
+  }
+
+  get composition(): TextComposition | undefined {
+    return this.composition_;
+  }
+
+  /** Includes the preview in place of the selected text, without committing it. */
+  get displayValue(): string {
+    if (!this.composition_) return this.value_;
+    const [start, end] = this.range();
+    return this.value_.slice(0, start) + this.composition_.text + this.value_.slice(end);
+  }
+
+  setValue(value: string): void {
+    this.composition_ = undefined;
+    this.value_ = value;
+    this.rebuildBoundaries();
+    this.anchor_ = this.focus_ = value.length;
+  }
+
+  setSelection(anchor: number, focus = anchor): void {
+    const nextAnchor = this.snap(anchor);
+    const nextFocus = this.snap(focus);
+    this.composition_ = undefined;
+    this.anchor_ = nextAnchor;
+    this.focus_ = nextFocus;
+  }
+
+  selectAll(): void {
+    this.setSelection(0, this.value_.length);
+  }
+
+  insert(text: string): void {
+    this.composition_ = undefined;
+    this.replaceSelection(text);
+  }
+
+  backspace(byWord = false): void {
+    this.delete('backward', byWord);
+  }
+
+  deleteForward(byWord = false): void {
+    this.delete('forward', byWord);
+  }
+
+  move(direction: 'left' | 'right', extend = false, byWord = false): void {
+    if (this.composition_) return;
+    const [start, end] = this.range();
+    const position =
+      !extend && start !== end
+        ? direction === 'left'
+          ? start
+          : end
+        : direction === 'left'
+          ? byWord
+            ? this.previousWord(this.focus_)
+            : this.previous(this.focus_)
+          : byWord
+            ? this.nextWord(this.focus_)
+            : this.next(this.focus_);
+    this.focus_ = position;
+    if (!extend) this.anchor_ = position;
+  }
+
+  moveToBoundary(boundary: 'start' | 'end', extend = false): void {
+    if (this.composition_) return;
+    this.focus_ = boundary === 'start' ? 0 : this.value_.length;
+    if (!extend) this.anchor_ = this.focus_;
+  }
+
+  updateComposition(text: string, selection?: readonly [number, number]): void {
+    this.composition_ = selection ? { text, selection: [selection[0], selection[1]] } : { text };
+  }
+
+  commitComposition(text: string): void {
+    this.composition_ = undefined;
+    this.replaceSelection(text);
+  }
+
+  cancelComposition(): void {
+    this.composition_ = undefined;
+  }
+
+  private delete(direction: 'backward' | 'forward', byWord: boolean): void {
+    if (this.composition_) return;
+    if (this.anchor_ === this.focus_) {
+      if (direction === 'backward') {
+        this.anchor_ = byWord ? this.previousWord(this.focus_) : this.previous(this.focus_);
+      } else {
+        this.focus_ = byWord ? this.nextWord(this.focus_) : this.next(this.focus_);
+      }
+    }
+    this.replaceSelection('');
+  }
+
+  private range(): [number, number] {
+    return [Math.min(this.anchor_, this.focus_), Math.max(this.anchor_, this.focus_)];
+  }
+
+  private replaceSelection(text: string): void {
+    const [start, end] = this.range();
+    if (start === end && text.length === 0) return;
+    this.value_ = this.value_.slice(0, start) + text + this.value_.slice(end);
+    this.rebuildBoundaries();
+    // Inserted text can combine with neighboring code points into one grapheme.
+    const desired = start + text.length;
+    this.anchor_ = this.focus_ =
+      this.boundaries.find((boundary) => boundary >= desired) ?? this.value_.length;
+  }
+
+  private rebuildBoundaries(): void {
+    this.boundaries.length = 0;
+    for (const segment of graphemeSegments(this.value_)) this.boundaries.push(segment.index);
+    this.boundaries.push(this.value_.length);
+  }
+
+  private snap(offset: number): number {
+    if (!Number.isFinite(offset)) throw new RangeError('Text selection offset must be finite.');
+    const clamped = Math.max(0, Math.min(this.value_.length, Math.trunc(offset)));
+    let result = 0;
+    for (const boundary of this.boundaries) {
+      if (boundary > clamped) break;
+      result = boundary;
+    }
+    return result;
+  }
+
+  private previous(offset: number): number {
+    let result = 0;
+    for (const boundary of this.boundaries) {
+      if (boundary >= offset) break;
+      result = boundary;
+    }
+    return result;
+  }
+
+  private next(offset: number): number {
+    return this.boundaries.find((boundary) => boundary > offset) ?? this.value_.length;
+  }
+
+  private previousWord(offset: number): number {
+    let current = this.snap(offset);
+    if (current === 0) return 0;
+    while (current > 0) {
+      const prev = this.previous(current);
+      if (charType(this.value_.slice(prev, current)) !== 'space') break;
+      current = prev;
+    }
+    if (current === 0) return 0;
+    const prev = this.previous(current);
+    const targetType = charType(this.value_.slice(prev, current));
+    while (current > 0) {
+      const p = this.previous(current);
+      if (charType(this.value_.slice(p, current)) !== targetType) break;
+      current = p;
+    }
+    return current;
+  }
+
+  private nextWord(offset: number): number {
+    let current = this.snap(offset);
+    const length = this.value_.length;
+    if (current >= length) return length;
+    while (current < length) {
+      const next = this.next(current);
+      if (charType(this.value_.slice(current, next)) !== 'space') break;
+      current = next;
+    }
+    if (current >= length) return length;
+    const next = this.next(current);
+    const targetType = charType(this.value_.slice(current, next));
+    while (current < length) {
+      const n = this.next(current);
+      if (charType(this.value_.slice(current, n)) !== targetType) break;
+      current = n;
+    }
+    return current;
+  }
+}

package/src/text/encoding.ts

@@ -0,0 +1,38 @@
+import { Buffer } from 'buffer';
+import * as iconv from 'iconv-lite';
+
+/** Configures conversion at byte boundaries; editor strings remain Unicode. */
+export class TextEncoding {
+  private charset_: string;
+
+  constructor(charset = 'utf-8') {
+    this.charset_ = TextEncoding.validate(charset);
+  }
+
+  get charset(): string {
+    return this.charset_;
+  }
+
+  setCharset(charset: string): void {
+    this.charset_ = TextEncoding.validate(charset);
+  }
+
+  /** Unrepresentable characters are replaced according to the selected codec. */
+  encode(value: string): Uint8Array {
+    return Uint8Array.from(iconv.encode(value, this.charset_));
+  }
+
+  /** Invalid byte sequences are replaced according to the selected codec. */
+  decode(value: Uint8Array): string {
+    return iconv.decode(
+      Buffer.from(value.buffer, value.byteOffset, value.byteLength),
+      this.charset_
+    );
+  }
+
+  private static validate(charset: string): string {
+    if (!iconv.encodingExists(charset))
+      throw new RangeError(`Unsupported text charset: ${charset}`);
+    return charset;
+  }
+}

package/src/text/index.ts

@@ -0,0 +1,13 @@
+export { TextEditor } from './editor';
+export { TextEncoding } from './encoding';
+export { TextInput } from './input';
+export type {
+  TextInputOptions,
+  TextInputEvent,
+  TextInputEventType,
+  TextInputCallback
+} from './input';
+export { SvgTextDecorations } from './svg-decorations';
+export type { SvgTextDecorationOptions, TextDecorationRect } from './svg-decorations';
+export type { TextComposition, TextSelection } from './editor';
+export { applyTextKeyboardEvent } from './keyboard';