@lucent-lang/lucent 0.0.4 → 0.1.0

package/dist/trace-Bi4hkmPx.js

@@ -0,0 +1,139 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/cli/trace.ts
+const CATEGORIES = [
+	"entry",
+	"lock",
+	"queue",
+	"run",
+	"native",
+	"completion",
+	"compute",
+	"copy",
+	"alloc",
+	"build"
+];
+const BUILD_PID = 1;
+function buildEvents(record) {
+	const startedAt = record.startedAt ?? {};
+	return record.nodes.map((node) => {
+		const args = {
+			kind: node.kind,
+			status: node.status,
+			...node.detail ? { detail: node.detail } : {}
+		};
+		const ms = record.timings[node.id];
+		if (ms === void 0 || startedAt[node.id] === void 0) return {
+			name: node.id,
+			cat: "build",
+			ph: "i",
+			s: "p",
+			ts: 0,
+			pid: BUILD_PID,
+			tid: 1,
+			args
+		};
+		return {
+			name: node.id,
+			cat: "build",
+			ph: "X",
+			ts: startedAt[node.id] * 1e3,
+			dur: ms * 1e3,
+			pid: BUILD_PID,
+			tid: 1,
+			args
+		};
+	});
+}
+const processName = (pid, name) => ({
+	name: "process_name",
+	ph: "M",
+	pid,
+	args: { name }
+});
+function mergeTraces(record, runtimes) {
+	const events = [];
+	if (record) events.push(processName(BUILD_PID, "lucent build"), ...buildEvents(record));
+	runtimes.forEach(({ name, trace }, i) => {
+		const pid = 2 + i;
+		events.push(processName(pid, name));
+		for (const e of trace.traceEvents) events.push({
+			...e,
+			pid
+		});
+	});
+	return {
+		traceEvents: events,
+		displayTimeUnit: "ms"
+	};
+}
+function summarize(trace) {
+	const totals = /* @__PURE__ */ new Map();
+	for (const e of trace.traceEvents) {
+		if (e.ph !== "X" || !e.cat) continue;
+		const total = totals.get(e.cat) ?? {
+			category: e.cat,
+			ms: 0,
+			count: 0
+		};
+		total.ms += (e.dur ?? 0) / 1e3;
+		total.count++;
+		const bytes = e.cat === "copy" ? Number(e.args?.value ?? 0) : 0;
+		if (bytes > 0) total.bytes = (total.bytes ?? 0) + bytes;
+		totals.set(e.cat, total);
+	}
+	const order = (c) => {
+		const i = CATEGORIES.indexOf(c);
+		return i < 0 ? CATEGORIES.length : i;
+	};
+	return { categories: [...totals.values()].sort((a, b) => order(a.category) - order(b.category)).map((t) => ({
+		...t,
+		ms: Math.round(t.ms * 1e3) / 1e3
+	})) };
+}
+function formatMs(ms) {
+	if (ms >= 1e3) return `${(ms / 1e3).toFixed(1)} s`;
+	return `${Number(ms.toPrecision(3))} ms`;
+}
+//#endregion
+//#region src/cli/commands/trace.ts
+const HOW = "run the app or its tests with LUCENT_TRACE=<file>.json and pass --runtime <file>; on a device, LUCENT_TRACE=platform (iOS, Instruments' os_signpost) or `adb shell setprop debug.lucent.trace 1` (Android, Perfetto's atrace)";
+function run({ root, flags, out }) {
+	const t = out.theme;
+	const recordFile = path.join(root, ".lucent", "build-record.json");
+	const record = fs.existsSync(recordFile) ? JSON.parse(fs.readFileSync(recordFile, "utf8")) : void 0;
+	const runtimeFiles = typeof flags.runtime === "string" ? flags.runtime.split(",").map((f) => path.resolve(root, f.trim())) : [];
+	if (!record && !runtimeFiles.length) {
+		out.error(`${t.error(t.symbols.fail)} no build record in ${path.join(root, ".lucent")} and no --runtime trace: build first, or ${HOW}`);
+		return 1;
+	}
+	const runtimes = [];
+	for (const file of runtimeFiles) {
+		if (!fs.existsSync(file)) {
+			out.error(`${t.error(t.symbols.fail)} no runtime trace at ${file}: ${HOW}`);
+			return 1;
+		}
+		runtimes.push({
+			name: path.basename(file),
+			trace: JSON.parse(fs.readFileSync(file, "utf8"))
+		});
+	}
+	const merged = mergeTraces(record, runtimes);
+	const target = typeof flags.out === "string" ? path.resolve(root, flags.out) : path.join(root, ".lucent", "trace.json");
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	fs.writeFileSync(target, `${JSON.stringify(merged)}\n`);
+	const shown = path.relative(root, target) || target;
+	out.print(`${t.success(t.symbols.ok)} wrote ${shown}  ${t.dim("open it in ui.perfetto.dev or chrome://tracing")}`);
+	if (record) {
+		const steps = Object.entries(record.timings).sort(([a], [b]) => (record.startedAt?.[a] ?? 0) - (record.startedAt?.[b] ?? 0)).map(([id, ms]) => `${id} ${formatMs(ms)}`);
+		out.print(`  ${"build".padEnd(16)} ${steps.join(" · ") || t.dim("nothing timed")}`);
+	}
+	for (const { name, trace } of runtimes) {
+		const causes = summarize(trace).categories.map((c) => `${c.category} ${formatMs(c.ms)}${c.bytes ? ` (${(c.bytes / 1e6).toFixed(1)} MB)` : ""}`);
+		const dropped = Number(trace.otherData?.dropped ?? 0);
+		out.print(`  ${name.padEnd(16)} ${causes.join(" · ") || t.dim("no spans")}${dropped ? t.dim(`  (${dropped} events dropped)`) : ""}`);
+	}
+	return 0;
+}
+//#endregion
+export { run };

package/lib/core.cjs

@@ -103,4 +103,371 @@ function now() {
   return typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
 }
 
-module.exports = { delay, error, errorCode, utf8Encode, utf8Decode, now };
+// An error nobody can catch (a cleanup's): the host's uncaught error
+// handler gets it, as native code's goes to the platform log.
+function reportUncaught(e) {
+  setTimeout(() => {
+    throw e;
+  }, 0);
+}
+
+// One promise that settles once, at the first of what `start`'s callbacks
+// report and the signal aborting; the cleanup `start` returns runs once, as
+// soon as it settles.
+function compose(signal, start) {
+  return new Promise((resolve, reject) => {
+    if (signal && signal.aborted) return void reject(signal.reason);
+
+    let settled = false;
+    let registered = false;
+    let cleanup;
+
+    const runCleanup = () => {
+      const f = cleanup;
+      cleanup = undefined;
+      if (typeof f !== "function") return;
+      try {
+        f();
+      } catch (e) {
+        reportUncaught(e);
+      }
+    };
+
+    const settle = (how, value) => {
+      if (settled) return;
+      settled = true;
+      if (signal) signal.removeEventListener("abort", onAbort);
+      how(value);
+      if (registered) runCleanup();
+    };
+
+    const onAbort = () => settle(reject, signal.reason);
+    if (signal) signal.addEventListener("abort", onAbort);
+
+    try {
+      cleanup = start({
+        open: () => !settled,
+        resolve: (value) => settle(resolve, value),
+        reject: (reason) => settle(reject, reason),
+      });
+    } catch (e) {
+      settle(reject, e);
+    }
+
+    registered = true;
+    if (settled) runCleanup();
+  });
+}
+
+function fromCallback(register, signal) {
+  return compose(signal, (c) =>
+    register(
+      (value) => void c.resolve(value),
+      (reason) => void c.reject(reason),
+    ),
+  );
+}
+
+function subscribe(register, onValue, signal) {
+  return compose(signal, (c) => {
+    const next = (value) => {
+      if (!c.open()) return;
+      try {
+        onValue(value);
+      } catch (e) {
+        c.reject(e);
+      }
+    };
+    return register(
+      next,
+      () => void c.resolve(undefined),
+      (error) => void c.reject(error),
+    );
+  });
+}
+
+// --- native buffers ---------------------------------------------------------
+
+const MAX_SIZE = Number.MAX_SAFE_INTEGER;
+
+const bufferCounts = { allocated: 0, adopted: 0, transfers: 0, copies: 0, bytesCopied: 0 };
+
+function countCopy(bytes) {
+  bufferCounts.copies++;
+  bufferCounts.bytesCopied += bytes;
+}
+
+// Each buffer's state, out of reach of the code using it: its bytes, open,
+// transferred or closed, and its borrows.
+const buffers = new WeakMap();
+const creating = Symbol("NativeBuffer");
+
+function invalidState(why) {
+  const e = new Error(`NativeBuffer ${why}`);
+  e.name = "InvalidStateError";
+  return e;
+}
+
+function stateOf(buffer) {
+  const s = buffers.get(buffer);
+  if (!s) throw new TypeError("not a NativeBuffer");
+  return s;
+}
+
+/** Refuses a use unless the buffer is open and, for `write`, unborrowed (reads need no writer). */
+function borrowable(s, write) {
+  if (s.state !== "open")
+    throw invalidState(s.state === "closed" ? "is closed" : "was transferred");
+  if (s.writing || (write && s.readers > 0)) throw invalidState("is borrowed");
+}
+
+/**
+ * Bytes native code owns, as the native runtime keeps them: borrowed for
+ * one call, moved by transfer() and compute, copied only by from() and
+ * toUint8Array(). Here the bytes a borrow lends are the buffer's own.
+ */
+class NativeBuffer {
+  constructor(token, bytes) {
+    if (token !== creating) throw new TypeError("Illegal constructor");
+    buffers.set(this, { bytes, state: "open", readers: 0, writing: false });
+  }
+
+  static allocate(size) {
+    if (!(size >= 0) || Math.trunc(size) !== size || size > MAX_SIZE)
+      throw new RangeError("Invalid buffer size");
+
+    bufferCounts.allocated++;
+    return new NativeBuffer(creating, new Uint8Array(size));
+  }
+
+  static from(bytes) {
+    const buffer = NativeBuffer.allocate(bytes.length);
+
+    stateOf(buffer).bytes.set(bytes);
+    countCopy(bytes.length);
+    return buffer;
+  }
+
+  static stats() {
+    return { ...bufferCounts };
+  }
+
+  get byteLength() {
+    const s = stateOf(this);
+    return s.state === "open" ? s.bytes.length : 0;
+  }
+
+  withRead(read) {
+    const s = stateOf(this);
+
+    borrowable(s, false);
+    s.readers++;
+    try {
+      return read(s.bytes);
+    } finally {
+      s.readers--;
+    }
+  }
+
+  withWrite(write) {
+    const s = stateOf(this);
+
+    borrowable(s, true);
+    s.writing = true;
+    try {
+      return write(s.bytes);
+    } finally {
+      s.writing = false;
+    }
+  }
+
+  toUint8Array() {
+    return this.withRead((bytes) => {
+      countCopy(bytes.length);
+      return bytes.slice();
+    });
+  }
+
+  transfer() {
+    const moved = beginTransfer(this);
+
+    commitTransfer(this);
+    return moved;
+  }
+
+  close() {
+    const s = stateOf(this);
+
+    if (s.state !== "open") return;
+    borrowable(s, true);
+
+    s.state = "closed";
+    s.bytes = new Uint8Array(0);
+  }
+
+  [Symbol.dispose]() {
+    this.close();
+  }
+}
+
+// A move in two steps, as a task's input is copied: the new buffer takes
+// the bytes at once, and the old one gives them up for good only once the
+// whole input has been copied.
+function beginTransfer(buffer) {
+  const s = stateOf(buffer);
+
+  borrowable(s, true);
+  s.state = "transferring";
+  return new NativeBuffer(creating, s.bytes);
+}
+
+function commitTransfer(buffer) {
+  const s = stateOf(buffer);
+
+  s.state = "transferred";
+  s.bytes = new Uint8Array(0);
+  bufferCounts.transfers++;
+}
+
+function abortTransfer(buffer) {
+  stateOf(buffer).state = "open";
+}
+
+/** What a copy refuses to copy: a DataCloneError, as structuredClone throws. */
+function dataCloneError(message) {
+  const e = new Error(message);
+  e.name = "DataCloneError";
+  return e;
+}
+
+/**
+ * A compute task's input, copied as the native runtime copies it: every
+ * object, array, map, set, date and byte buffer reached is copied once
+ * (aliases stay aliases, cycles survive), objects keep their class, and
+ * views of one buffer stay views of one copied buffer. A NativeBuffer
+ * moves instead, once: `moved` collects the moves to commit or undo.
+ */
+function transportCopy(value, copies = new Map(), moved = []) {
+  if (value === null || (typeof value !== "object" && typeof value !== "function")) return value;
+  if (typeof value === "function")
+    throw dataCloneError("A function cannot be copied to a compute task");
+
+  const known = copies.get(value);
+  if (known) return known;
+
+  if (value instanceof NativeBuffer) {
+    const successor = beginTransfer(value);
+    moved.push(value);
+    copies.set(value, successor);
+    return successor;
+  }
+
+  if (value instanceof Uint8Array) {
+    let buffer = copies.get(value.buffer);
+    if (!buffer) {
+      buffer = value.buffer.slice(0);
+      copies.set(value.buffer, buffer);
+    }
+    const view = new Uint8Array(buffer, value.byteOffset, value.length);
+    copies.set(value, view);
+    return view;
+  }
+
+  if (value instanceof Date) {
+    const date = new Date(value.getTime());
+    copies.set(value, date);
+    return date;
+  }
+
+  if (value instanceof Map) {
+    const map = new Map();
+    copies.set(value, map);
+    for (const [k, v] of value)
+      map.set(transportCopy(k, copies, moved), transportCopy(v, copies, moved));
+    return map;
+  }
+
+  if (value instanceof Set) {
+    const set = new Set();
+    copies.set(value, set);
+    for (const v of value) set.add(transportCopy(v, copies, moved));
+    return set;
+  }
+
+  if (Array.isArray(value)) {
+    const array = [];
+    copies.set(value, array);
+    for (const v of value) array.push(transportCopy(v, copies, moved));
+    return array;
+  }
+
+  if (value instanceof Promise || value instanceof AbortSignal || value instanceof AbortController)
+    throw dataCloneError(`A ${value.constructor.name} cannot be copied to a compute task`);
+
+  const object = Object.create(Object.getPrototypeOf(value));
+  copies.set(value, object);
+  // Defined, not assigned: an own "__proto__" key stays a key.
+  for (const key of Object.keys(value))
+    Object.defineProperty(object, key, {
+      value: transportCopy(value[key], copies, moved),
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    });
+  return object;
+}
+
+/**
+ * Runs `task(input)` as a compute task would, on this thread: the input is
+ * copied now, the task runs in a later turn, and aborting the signal first
+ * rejects with its reason (the task then never runs).
+ */
+function compute(task, input, options) {
+  const signal = options && options.signal;
+
+  return new Promise((resolve, reject) => {
+    let copy;
+    const moved = [];
+    try {
+      copy = transportCopy(input, new Map(), moved);
+    } catch (e) {
+      moved.forEach(abortTransfer);
+      return void reject(e);
+    }
+    moved.forEach(commitTransfer);
+
+    if (signal && signal.aborted) return void reject(signal.reason);
+
+    let settled = false;
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      if (signal) signal.removeEventListener("abort", onAbort);
+      try {
+        resolve(task(copy));
+      } catch (e) {
+        reject(e);
+      }
+    }, 0);
+    if (signal) signal.addEventListener("abort", onAbort);
+  });
+}
+
+module.exports = {
+  delay,
+  error,
+  errorCode,
+  utf8Encode,
+  utf8Decode,
+  now,
+  fromCallback,
+  subscribe,
+  compute,
+  NativeBuffer,
+};

package/lib/sdk/android.d.ts

@@ -1,8 +1,61 @@
 // lucent:android — Android helpers for platform code.
-import type { Context } from "lucent:android/android.content";
+import type { Activity, Instrumentation_ActivityResult } from "lucent:android/android.app";
+import type { Context, Intent } from "lucent:android/android.content";
 
 /** The application Context. */
 export declare function appContext(): Context;
 
 /** Whether the device runs at least API level `api` (`Build.VERSION.SDK_INT >= api`). */
 export declare function available(platform: "android", api: number): boolean;
+
+/**
+ * The Activity in front: the one last created, started or resumed and not
+ * destroyed, or null (before the first, between two, after the last).
+ * Lucent holds Activities weakly: use this one now, on the main thread
+ * (inside `main()`), and ask again later rather than keeping it.
+ */
+export declare function currentActivity(): Activity | null;
+
+/**
+ * Starts `intent` from the Activity in front and resolves with its result
+ * (`getResultCode()`, `getResultData()`). The request survives the app's
+ * Activity being recreated meanwhile. Rejects with `ERR_NO_ACTIVITY` without
+ * an Activity, `ERR_ACTIVITY_NOT_FOUND` when no app handles the intent, and
+ * the signal's reason if it aborts first: the answer, if it still comes, is
+ * dropped (Lucent closes what it started when Android lets it).
+ */
+export declare function startActivityForResult(
+  intent: Intent,
+  signal?: AbortSignal,
+): Promise<Instrumentation_ActivityResult>;
+
+/**
+ * Asks for runtime permissions (`"android.permission.CAMERA"`), and
+ * resolves with whether each was granted, in order. Requests wait for the
+ * one before them, as Android asks one at a time. Rejects like
+ * `startActivityForResult`.
+ */
+export declare function requestPermissions(
+  permissions: string[],
+  signal?: AbortSignal,
+): Promise<boolean[]>;
+
+/** The lifecycle events of the app's Activities, and a new intent sent to one. */
+export type ActivityEvent =
+  | "created"
+  | "started"
+  | "resumed"
+  | "paused"
+  | "stopped"
+  | "destroyed"
+  | "newIntent";
+
+/**
+ * Runs `handler` after each `event` of the app's Activities, with the
+ * Activity (and the intent, for "newIntent"), in a turn of the calling
+ * context. Returns the function that stops it.
+ */
+export declare function onActivityEvent(
+  event: ActivityEvent,
+  handler: (activity: Activity, intent: Intent | null) => void,
+): () => void;

package/lib/sdk/compose.d.ts

@@ -0,0 +1,94 @@
+/**
+ * lucent:compose — Jetpack Compose, for a component's content on Android.
+ *
+ * Experimental and internal: this module resolves only when the
+ * LUCENT_VIEWS environment variable is `fabric`, and changes without notice
+ * until Lucent's views are public.
+ *
+ * A component returns its content: JSX, compiled to Kotlin. A composable
+ * showing UI is an element (`<Box modifier={…}>`), whose props are
+ * Kotlin's named arguments and whose children are its trailing content
+ * lambda, or a function of the lambda's scope (`{(row) => …}`); a lazy
+ * list's items are elements of its scope (`{(list) => <list.items
+ * items={…} key={…}>…</list.items>}`). The component's statements that
+ * compose (`animateDpAsState(…)`, `remember(…)`, `LaunchedEffect(…)`)
+ * run in the content, in order, before what the JSX shows; the rest of
+ * its code is its setup, which runs once and reads none of their values.
+ * The content reads the setup's props, signals and functions: a number,
+ * boolean or string the setup computes is Compose state, and a setup
+ * function the content calls from a callback runs as Lucent code. Other
+ * functions take Kotlin's parameters in order, an options object holding
+ * the defaulted ones where Kotlin's order cannot (`spring({ stiffness })`);
+ * modifiers, animations and effects are Compose's.
+ *
+ * A value Compose pairs with the callback of its changes (`value` and
+ * `onValueChange`) takes a setup signal bound to both instead,
+ * `bind(signal)` from lucent:ui.
+ *
+ * Below lucent:compose's own declarations come Compose's, under their own
+ * names, made from the bindings of the Compose release Lucent builds with.
+ * Float, Int, Long, Short and Byte are Kotlin's number types: a number the
+ * body passes to one is converted.
+ *
+ * @experimental
+ */
+import type { ViewGroup } from "lucent:android/android.view";
+import type { Bound } from "lucent:ui";
+
+/** Kotlin's Float: a number, converted where the body passes it. */
+export type Float = number & { readonly "lucent:compose.Float"?: never };
+/** Kotlin's Int. */
+export type Int = number & { readonly "lucent:compose.Int"?: never };
+/** Kotlin's Long. */
+export type Long = number & { readonly "lucent:compose.Long"?: never };
+/** Kotlin's Short. */
+export type Short = number & { readonly "lucent:compose.Short"?: never };
+/** Kotlin's Byte. */
+export type Byte = number & { readonly "lucent:compose.Byte"?: never };
+
+/**
+ * What an element shows (`<Box …/>`): an item of content, the value of
+ * JSX, never a value setup holds.
+ */
+export interface Composed {
+  readonly "lucent:compose.Composed": true;
+}
+
+/** Content: what composables show, in order, or nothing where a condition is false. */
+export type Shown = Composed | false | null | undefined | readonly Shown[];
+
+/** A @Composable content lambda given as a prop: its statements compose, and it returns what it shows. */
+export type Content = () => Shown;
+
+/**
+ * A content lambda composed in a receiver scope (a Row's RowScope), given
+ * as a prop: its first parameter is the scope, whose methods and Modifier
+ * run in it.
+ */
+export type ScopedContent<S> = (scope: S) => Shown;
+
+/**
+ * An element's children composed in a receiver scope: what they show, or
+ * a function of the scope showing it, for children that use the scope
+ * (`{(row) => <Text modifier={row.Modifier.weight(1)} … />}`).
+ */
+export type ScopedChildren<S> = Shown | ((scope: S) => Shown);
+
+/**
+ * How TypeScript types an Android file's JSX: an element is a composable,
+ * a function of its props whose children are its `children` prop.
+ */
+export declare namespace JSX {
+  type Element = Composed;
+
+  interface ElementChildrenAttribute {
+    children: {};
+  }
+
+  interface IntrinsicElements {}
+}
+
+/** The Android view hosting a composition: the view a component returning JSX makes. */
+export declare class ComposeView extends ViewGroup {
+  private constructor();
+}