@lucent-lang/lucent 0.0.4

package/dist/steps--_h-FFS7.js

@@ -0,0 +1,24 @@
+import { a as visibleWidth, n as duration } from "./format-D9fnIMEx.js";
+//#region src/cli/ui/steps.ts
+const TIME_COLUMN = 40;
+function stepLine(r, theme) {
+	const text = `${r.status === "failed" ? theme.error(theme.symbols.fail) : r.status === "skipped" ? theme.dim(theme.symbols.off) : theme.success(theme.symbols.ok)} ${r.label}${r.detail ? `  ${theme.dim(r.detail)}` : ""}`;
+	const time = r.status === "cached" ? "cached" : r.ms !== void 0 ? duration(r.ms) : "";
+	if (!time) return text;
+	return `${text}${" ".repeat(Math.max(2, TIME_COLUMN - visibleWidth(text)))}${theme.dim(time)}`;
+}
+function plainSteps(print, theme) {
+	const results = [];
+	return {
+		results,
+		start: () => {},
+		finish(r) {
+			results.push(r);
+			print(stepLine(r, theme));
+		},
+		flush: async () => {},
+		close: async () => {}
+	};
+}
+//#endregion
+export { stepLine as n, plainSteps as t };

package/dist/theme-uv5bc0aK.js

@@ -0,0 +1,134 @@
+import "node:module";
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+//#region src/cli/ui/theme.ts
+var import_picocolors = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
+	let p = process || {};
+	let argv = p.argv || [];
+	let env = p.env || {};
+	let isColorSupported = !(!!env.NO_COLOR || argv.includes("--no-color")) && (!!env.FORCE_COLOR || argv.includes("--color") || p.platform === "win32" || (p.stdout || {}).isTTY && env.TERM !== "dumb" || !!env.CI);
+	let formatter = (open, close, replace = open) => (input) => {
+		let string = "" + input, index = string.indexOf(close, open.length);
+		return ~index ? open + replaceClose(string, close, replace, index) + close : open + string + close;
+	};
+	let replaceClose = (string, close, replace, index) => {
+		let result = "", cursor = 0;
+		do {
+			result += string.substring(cursor, index) + replace;
+			cursor = index + close.length;
+			index = string.indexOf(close, cursor);
+		} while (~index);
+		return result + string.substring(cursor);
+	};
+	let createColors = (enabled = isColorSupported) => {
+		let f = enabled ? formatter : () => String;
+		return {
+			isColorSupported: enabled,
+			reset: f("\x1B[0m", "\x1B[0m"),
+			bold: f("\x1B[1m", "\x1B[22m", "\x1B[22m\x1B[1m"),
+			dim: f("\x1B[2m", "\x1B[22m", "\x1B[22m\x1B[2m"),
+			italic: f("\x1B[3m", "\x1B[23m"),
+			underline: f("\x1B[4m", "\x1B[24m"),
+			inverse: f("\x1B[7m", "\x1B[27m"),
+			hidden: f("\x1B[8m", "\x1B[28m"),
+			strikethrough: f("\x1B[9m", "\x1B[29m"),
+			black: f("\x1B[30m", "\x1B[39m"),
+			red: f("\x1B[31m", "\x1B[39m"),
+			green: f("\x1B[32m", "\x1B[39m"),
+			yellow: f("\x1B[33m", "\x1B[39m"),
+			blue: f("\x1B[34m", "\x1B[39m"),
+			magenta: f("\x1B[35m", "\x1B[39m"),
+			cyan: f("\x1B[36m", "\x1B[39m"),
+			white: f("\x1B[37m", "\x1B[39m"),
+			gray: f("\x1B[90m", "\x1B[39m"),
+			bgBlack: f("\x1B[40m", "\x1B[49m"),
+			bgRed: f("\x1B[41m", "\x1B[49m"),
+			bgGreen: f("\x1B[42m", "\x1B[49m"),
+			bgYellow: f("\x1B[43m", "\x1B[49m"),
+			bgBlue: f("\x1B[44m", "\x1B[49m"),
+			bgMagenta: f("\x1B[45m", "\x1B[49m"),
+			bgCyan: f("\x1B[46m", "\x1B[49m"),
+			bgWhite: f("\x1B[47m", "\x1B[49m"),
+			blackBright: f("\x1B[90m", "\x1B[39m"),
+			redBright: f("\x1B[91m", "\x1B[39m"),
+			greenBright: f("\x1B[92m", "\x1B[39m"),
+			yellowBright: f("\x1B[93m", "\x1B[39m"),
+			blueBright: f("\x1B[94m", "\x1B[39m"),
+			magentaBright: f("\x1B[95m", "\x1B[39m"),
+			cyanBright: f("\x1B[96m", "\x1B[39m"),
+			whiteBright: f("\x1B[97m", "\x1B[39m"),
+			bgBlackBright: f("\x1B[100m", "\x1B[49m"),
+			bgRedBright: f("\x1B[101m", "\x1B[49m"),
+			bgGreenBright: f("\x1B[102m", "\x1B[49m"),
+			bgYellowBright: f("\x1B[103m", "\x1B[49m"),
+			bgBlueBright: f("\x1B[104m", "\x1B[49m"),
+			bgMagentaBright: f("\x1B[105m", "\x1B[49m"),
+			bgCyanBright: f("\x1B[106m", "\x1B[49m"),
+			bgWhiteBright: f("\x1B[107m", "\x1B[49m")
+		};
+	};
+	module.exports = createColors();
+	module.exports.createColors = createColors;
+})))(), 1);
+const UNICODE = {
+	brand: "◆",
+	ok: "✓",
+	fail: "✗",
+	warn: "!",
+	busy: "◐",
+	on: "●",
+	off: "○",
+	bar: "│",
+	rule: "─",
+	ellipsis: "…"
+};
+const ASCII = {
+	brand: "*",
+	ok: "+",
+	fail: "x",
+	warn: "!",
+	busy: "~",
+	on: "o",
+	off: ".",
+	bar: "|",
+	rule: "-",
+	ellipsis: "..."
+};
+function createTheme(terminal) {
+	const c = import_picocolors.default.createColors(terminal.color);
+	const violet = terminal.color ? (s) => `\x1b[38;5;141m${s}\x1b[39m` : (s) => s;
+	return {
+		terminal,
+		symbols: terminal.unicode ? UNICODE : ASCII,
+		brand: violet,
+		success: c.green,
+		error: c.red,
+		warn: c.yellow,
+		progress: c.cyan,
+		dim: c.dim,
+		bold: c.bold
+	};
+}
+//#endregion
+export { createTheme as t };

package/dist/tsconfig-S4uyLNzf.js

@@ -0,0 +1,59 @@
+import ts from "typescript";
+//#region src/cli/tsconfig.ts
+const ENTRY = "\"lucent:*\": [\"./.lucent/native/types/*\"]";
+function withLucentPaths(text) {
+	const { error } = ts.parseConfigFileTextToJson("tsconfig.json", text);
+	if (error) throw new Error(`tsconfig.json: ${ts.flattenDiagnosticMessageText(error.messageText, "\n")}`);
+	const sf = ts.parseJsonText("tsconfig.json", text);
+	const root = sf.statements[0]?.expression;
+	if (!root || !ts.isObjectLiteralExpression(root)) throw new Error("tsconfig.json: expected an object");
+	const options = property(root, "compilerOptions");
+	if (!options) return insert(text, sf, root, `"compilerOptions": { "paths": { ${ENTRY} } }`);
+	const paths = property(options, "paths");
+	if (!paths) return insert(text, sf, options, `"paths": { ${ENTRY} }`);
+	if (named(paths, "lucent:*")) return void 0;
+	return insert(text, sf, paths, ENTRY);
+}
+function withLucentTsconfig(text) {
+	const indexed = withCompilerOption(text, "noUncheckedIndexedAccess", "true");
+	return withLucentPaths(indexed ?? text) ?? indexed;
+}
+function withCompilerOption(text, name, value) {
+	const { error } = ts.parseConfigFileTextToJson("tsconfig.json", text);
+	if (error) throw new Error(`tsconfig.json: ${ts.flattenDiagnosticMessageText(error.messageText, "\n")}`);
+	const sf = ts.parseJsonText("tsconfig.json", text);
+	const root = sf.statements[0]?.expression;
+	if (!root || !ts.isObjectLiteralExpression(root)) throw new Error("tsconfig.json: expected an object");
+	const options = property(root, "compilerOptions");
+	if (!options) return insert(text, sf, root, `"compilerOptions": { "${name}": ${value} }`);
+	const current = named(options, name);
+	if (!current) return insert(text, sf, options, `"${name}": ${value}`);
+	if (current.initializer.getText(sf) === value) return void 0;
+	return `${text.slice(0, current.initializer.getStart(sf))}${value}${text.slice(current.initializer.getEnd())}`;
+}
+function named(o, name) {
+	return o.properties.find((p) => ts.isPropertyAssignment(p) && ts.isStringLiteral(p.name) && p.name.text === name);
+}
+function property(o, name) {
+	const value = named(o, name)?.initializer;
+	if (value === void 0) return void 0;
+	if (!ts.isObjectLiteralExpression(value)) throw new Error(`tsconfig.json: "${name}" should be an object`);
+	return value;
+}
+function insert(text, sf, o, member) {
+	const open = o.getStart(sf);
+	const last = o.properties.at(-1);
+	if (!last) return `${text.slice(0, open)}{ ${member} }${text.slice(o.getEnd())}`;
+	const line = (pos) => sf.getLineAndCharacterOfPosition(pos).line;
+	if (line(last.getStart(sf)) === line(open)) return `${text.slice(0, last.getEnd())}, ${member}${text.slice(last.getEnd())}`;
+	const lineStart = sf.getPositionOfLineAndCharacter(line(last.getStart(sf)), 0);
+	const indent = text.slice(lineStart, last.getStart(sf));
+	const comma = /^\s*,/.exec(text.slice(last.getEnd()));
+	if (comma) {
+		const at = last.getEnd() + comma[0].length;
+		return `${text.slice(0, at)}\n${indent}${member},${text.slice(at)}`;
+	}
+	return `${text.slice(0, last.getEnd())},\n${indent}${member}${text.slice(last.getEnd())}`;
+}
+//#endregion
+export { withLucentTsconfig as n, withLucentPaths as t };

package/dist/version-bqpIO5sP.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/cli/version.ts
+let found;
+function lucentPackage() {
+	if (found) return found;
+	for (let dir = path.dirname(fileURLToPath(import.meta.url)); path.dirname(dir) !== dir; dir = path.dirname(dir)) {
+		const file = path.join(dir, "package.json");
+		if (!fs.existsSync(file)) continue;
+		const pkg = JSON.parse(fs.readFileSync(file, "utf8"));
+		if (pkg.name === "@lucent-lang/lucent") return found = {
+			dir,
+			version: pkg.version ?? "0.0.0"
+		};
+	}
+	throw new Error("lucent is not inside the @lucent-lang/lucent package");
+}
+function version() {
+	return lucentPackage().version;
+}
+function packageFile(relative) {
+	return path.join(lucentPackage().dir, relative);
+}
+//#endregion
+export { version as n, packageFile as t };

package/gradle/lucent-classpath.gradle

@@ -0,0 +1,38 @@
+// Registers lucentClasspath in the app project it is applied to: writes the
+// app's resolved compile classpath (AARs and jars) to
+// .lucent/android-classpath.json, so lucent:android/<package> can bind any
+// library the app links (AndroidX, Play services, Firebase…).
+// Applied by lucent.gradle (the app's Gradle task) and by
+// lucent-classpath.init.gradle (when lucent build asks Gradle). In an app
+// with lucent.gradle, lucent build's run applies it twice: once registers.
+if (ext.has("lucentClasspathApplied")) return
+ext.lucentClasspathApplied = true
+pluginManager.withPlugin("com.android.application") {
+  // Registered after the Android plugin's own afterEvaluate, which creates the variants' configurations.
+  afterEvaluate {
+    def out = new File(rootProject.projectDir.parentFile, ".lucent/android-classpath.json")
+    def artifactType = Attribute.of("artifactType", String)
+    def compileClasspath = configurations.findByName("debugCompileClasspath") ?: configurations.findByName("releaseCompileClasspath")
+    if (compileClasspath == null) return
+    // Libraries from repositories only: the app's other projects (autolinked
+    // modules, Lucent's own) would have to be built first, and their preBuild
+    // runs lucentBuild, which needs this classpath.
+    def viewOf = { String type ->
+      compileClasspath.incoming.artifactView {
+        lenient(true)
+        componentFilter { it instanceof org.gradle.api.artifacts.component.ModuleComponentIdentifier }
+        attributes.attribute(artifactType, type)
+      }.files
+    }
+    def aars = viewOf("aar")
+    def jars = viewOf("jar")
+    tasks.register("lucentClasspath") {
+      inputs.files(aars, jars)
+      outputs.file(out)
+      doLast {
+        out.parentFile.mkdirs()
+        out.text = groovy.json.JsonOutput.prettyPrint(groovy.json.JsonOutput.toJson([aars: aars.files*.absolutePath.sort(), jars: jars.files*.absolutePath.sort()]))
+      }
+    }
+  }
+}

package/gradle/lucent-classpath.init.gradle

@@ -0,0 +1,6 @@
+// Gradle init script, passed by lucent build with --init-script: registers
+// lucentClasspath in the app project without touching the app's build files.
+def script = new File(buildscript.sourceFile.parentFile, "lucent-classpath.gradle")
+gradle.allprojects { project ->
+  if (project.path == ":app") project.apply(from: script)
+}

package/gradle/lucent.gradle

@@ -0,0 +1,24 @@
+// Lucent's Gradle task. lucent init applies it in android/app/build.gradle
+// (and the Expo config plugin during prebuild):
+//
+//   apply from: new File(new File(["node", "--print", "require.resolve('@lucent-lang/lucent/package.json')"].execute(null, rootDir).text.trim()).parentFile, "gradle/lucent.gradle")
+//
+// Every build then runs `lucent build` first, so .lucent/native matches the
+// *.lucent.ts sources however the app is built: Android Studio, ./gradlew, CI.
+def lucentDir = buildscript.sourceFile.parentFile
+apply from: new File(lucentDir, "lucent-classpath.gradle")
+
+def lucentBuild = tasks.register("lucentBuild", Exec) {
+  description = "Compiles the app's *.lucent.ts modules into .lucent/native"
+  group = "lucent"
+  dependsOn "lucentClasspath"
+  workingDir rootProject.projectDir.parentFile
+  // lucentClasspath just resolved the classpath in this build: lucent build must not start Gradle again.
+  environment "LUCENT_GRADLE_CLASSPATH", "1"
+  commandLine "node", new File(lucentDir, "../bin/lucent.cjs").canonicalPath, "build"
+}
+
+// Before any project's build, the native package's included.
+rootProject.allprojects { p ->
+  p.tasks.matching { it.name == "preBuild" }.configureEach { dependsOn(lucentBuild) }
+}

package/lib/core.cjs

@@ -0,0 +1,106 @@
+"use strict";
+// JavaScript implementations of lucent:core, used when a Lucent module
+// runs as plain JavaScript: the differential e2e harness, lucent bench's
+// JavaScript side, and apps' own tests (@lucent-lang/lucent/core). Native
+// builds use the C++ runtime.
+
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (!signal) return void setTimeout(resolve, ms);
+    if (signal.aborted) return void reject(signal.reason);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort);
+  });
+}
+
+function error(code, message) {
+  const e = new Error(message);
+  e.code = code;
+  return e;
+}
+
+function errorCode(e) {
+  return typeof e.code === "string" ? e.code : undefined;
+}
+
+function utf8Encode(s) {
+  const out = [];
+  for (let i = 0; i < s.length; i++) {
+    let cp = s.charCodeAt(i);
+    if (cp >= 0xd800 && cp <= 0xdbff && i + 1 < s.length) {
+      const lo = s.charCodeAt(i + 1);
+      if (lo >= 0xdc00 && lo <= 0xdfff) {
+        cp = 0x10000 + ((cp - 0xd800) << 10) + (lo - 0xdc00);
+        i++;
+      } else cp = 0xfffd;
+    } else if (cp >= 0xd800 && cp <= 0xdfff) cp = 0xfffd;
+    if (cp < 0x80) out.push(cp);
+    else if (cp < 0x800) out.push(0xc0 | (cp >> 6), 0x80 | (cp & 63));
+    else if (cp < 0x10000) out.push(0xe0 | (cp >> 12), 0x80 | ((cp >> 6) & 63), 0x80 | (cp & 63));
+    else
+      out.push(
+        0xf0 | (cp >> 18),
+        0x80 | ((cp >> 12) & 63),
+        0x80 | ((cp >> 6) & 63),
+        0x80 | (cp & 63),
+      );
+  }
+  return new Uint8Array(out);
+}
+
+function utf8Decode(bytes) {
+  let out = "";
+  let i = 0;
+  const n = bytes.length;
+  const cont = (k) => (i + k < n && (bytes[i + k] & 0xc0) === 0x80 ? bytes[i + k] & 63 : -1);
+  while (i < n) {
+    const c = bytes[i];
+    let cp = 0xfffd;
+    let len = 1;
+    if (c < 0x80) cp = c;
+    else if ((c & 0xe0) === 0xc0) {
+      const a = cont(1);
+      if (a >= 0 && c >= 0xc2) {
+        cp = ((c & 31) << 6) | a;
+        len = 2;
+      }
+    } else if ((c & 0xf0) === 0xe0) {
+      const a = cont(1),
+        b = cont(2);
+      if (a >= 0 && b >= 0) {
+        const v = ((c & 15) << 12) | (a << 6) | b;
+        if (v >= 0x800) {
+          cp = v;
+          len = 3;
+        }
+      }
+    } else if ((c & 0xf8) === 0xf0) {
+      const a = cont(1),
+        b = cont(2),
+        d = cont(3);
+      if (a >= 0 && b >= 0 && d >= 0) {
+        const v = ((c & 7) << 18) | (a << 12) | (b << 6) | d;
+        if (v >= 0x10000 && v <= 0x10ffff) {
+          cp = v;
+          len = 4;
+        }
+      }
+    }
+    out += String.fromCodePoint(cp);
+    i += len;
+  }
+  return out;
+}
+
+function now() {
+  return typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+}
+
+module.exports = { delay, error, errorCode, utf8Encode, utf8Decode, now };

package/lib/globals.d.ts

@@ -0,0 +1,36 @@
+// Globals available to Lucent modules beyond the ES2022 library. Only the
+// Lucent compiler loads this file; React Native, Node and the DOM declare
+// compatible versions, so the same source type-checks in an app's editor.
+
+interface Console {
+  log(...data: unknown[]): void;
+  info(...data: unknown[]): void;
+  debug(...data: unknown[]): void;
+  warn(...data: unknown[]): void;
+  error(...data: unknown[]): void;
+}
+
+declare var console: Console;
+
+interface AbortSignal {
+  readonly aborted: boolean;
+  /** Not available in Lucent code: catch the error from throwIfAborted() or delay() instead. */
+  readonly reason: any;
+  throwIfAborted(): void;
+  addEventListener(type: "abort", listener: () => void): void;
+}
+
+declare var AbortSignal: {
+  prototype: AbortSignal;
+};
+
+interface AbortController {
+  readonly signal: AbortSignal;
+  /** In Lucent code, `reason` must be an Error. */
+  abort(reason?: any): void;
+}
+
+declare var AbortController: {
+  prototype: AbortController;
+  new (): AbortController;
+};

package/lib/sdk/android.d.ts

@@ -0,0 +1,8 @@
+// lucent:android — Android helpers for platform code.
+import type { Context } 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;

package/lib/sdk/core.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Helpers available to Lucent modules. Each one has a native implementation
+ * in the Lucent runtime and a JavaScript implementation (the e2e harness's
+ * core.js) so the same source also runs as plain TypeScript.
+ */
+
+/** Resolves after `ms` milliseconds; rejects with the signal's reason if it aborts first. */
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+
+/** An Error with a machine-readable `code`, visible to JavaScript as `error.code`. */
+export declare function error(code: string, message: string): Error;
+
+/** The `code` of an error created with `error()`, or undefined. */
+export declare function errorCode(e: Error): string | undefined;
+
+/** UTF-8 encoding of a string (like `new TextEncoder().encode(s)`). */
+export declare function utf8Encode(s: string): Uint8Array;
+
+/** Decodes UTF-8 bytes (like `new TextDecoder().decode(b)`), replacing invalid sequences. */
+export declare function utf8Decode(bytes: Uint8Array): string;
+
+/** Milliseconds from a monotonic clock, for measuring durations. */
+export declare function now(): number;

package/lib/sdk/ios.d.ts

@@ -0,0 +1,33 @@
+// lucent:ios — iOS helpers for platform code.
+
+/** Whether the OS is at least `major.minor` (Swift's `#available`). */
+export declare function available(platform: "ios", major: number, minor?: number): boolean;
+
+/** The root of Objective-C objects. Values of type `Any` (`id`) arrive as NSObjects. */
+export declare class NSObject {
+  private readonly __lucent_NSObject: never;
+  protected constructor();
+}
+
+/** What can go where Objective-C takes `Any` (`id`), CoreFoundation values included. */
+export type ObjCValue = string | number | boolean | Uint8Array | Date | NSObject | null;
+
+/** The main dispatch queue (dispatch_get_main_queue()), for APIs that take a queue. */
+export declare function mainQueue(): NSObject;
+
+/** Swift's `as? String`: the string an `Any` holds, or null. */
+export declare function asString(value: NSObject | null): string | null;
+/** Swift's `as? Double` (an NSNumber). */
+export declare function asNumber(value: NSObject | null): number | null;
+/** Swift's `as? Bool` (an NSNumber). */
+export declare function asBoolean(value: NSObject | null): boolean | null;
+/** Swift's `as? Data`. */
+export declare function asData(value: NSObject | null): Uint8Array | null;
+/** Swift's `as? Date`. */
+export declare function asDate(value: NSObject | null): Date | null;
+
+/** An out-parameter of a C function (`CFTypeRef *`): pass it, then read `value`. */
+export declare class Out<T> {
+  constructor();
+  readonly value: T | null;
+}

package/lib/sdk/platform.d.ts

@@ -0,0 +1,8 @@
+// lucent:platform — which platform the code runs on.
+
+/**
+ * The platform: `if (PLATFORM === "ios") { … } else { … }` and
+ * `PLATFORM === "ios" ? … : …` compile each platform's branch only, so a
+ * shared module can use `lucent:ios/…` and `lucent:android/…` in them.
+ */
+export declare const PLATFORM: "ios" | "android";

package/lib/sdk/thread.d.ts

@@ -0,0 +1,8 @@
+// lucent:thread — thread affinity for platform code.
+
+/**
+ * Runs `f` on the platform's main thread (the main queue on iOS, the main
+ * Looper on Android) and resolves with its result. Main-thread-only SDK
+ * APIs may only be used inside `f`.
+ */
+export declare function main<T>(f: () => T): Promise<T>;

package/metro/index.cjs

@@ -0,0 +1,72 @@
+"use strict";
+// Metro integration. `*.lucent.ts` files stay the source of truth for types;
+// when bundling, their contents are replaced by the generated JS proxy that
+// forwards to the native module (written by `lucent build`).
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+/**
+ * Wraps a Metro config:
+ *   module.exports = withLucent(getDefaultConfig(__dirname));
+ *
+ * When Metro runs as a dev server, `lucent dev --compact` keeps
+ * `.lucent/native` up to date while you edit *.lucent.ts files, one line
+ * per build in Metro's output (it never reads Metro's keys; for the full
+ * dashboard, run `lucent dev` in a terminal of its own). Set
+ * `{ watch: false }` or LUCENT_WATCH=0 to turn that off (LUCENT_WATCH=1 forces it).
+ */
+function withLucent(config, options = {}) {
+  if (shouldWatch(options)) startWatcher(config.projectRoot || process.cwd());
+  const upstream =
+    (config.transformer && config.transformer.babelTransformerPath) || defaultTransformer();
+  // Transformer workers inherit the environment.
+  process.env.LUCENT_UPSTREAM_TRANSFORMER = upstream;
+  return {
+    ...config,
+    transformer: {
+      ...config.transformer,
+      babelTransformerPath: path.join(__dirname, "transformer.cjs"),
+    },
+  };
+}
+
+function defaultTransformer() {
+  for (const candidate of [
+    "@react-native/metro-babel-transformer",
+    "@expo/metro-config/babel-transformer",
+  ]) {
+    try {
+      return require.resolve(candidate, { paths: [process.cwd()] });
+    } catch {
+      // try the next one
+    }
+  }
+  throw new Error(
+    "Lucent: could not find Metro's babel transformer; set transformer.babelTransformerPath first",
+  );
+}
+
+function shouldWatch(options) {
+  if (options.watch !== undefined) return options.watch;
+  if (process.env.LUCENT_WATCH === "0") return false;
+  if (process.env.LUCENT_WATCH === "1") return true;
+  // Dev servers: `react-native start`, `expo start`, `expo run:ios|android`.
+  return process.argv.some((a) => a === "start" || a === "run:ios" || a === "run:android");
+}
+
+let watcher;
+
+function startWatcher(root) {
+  // Metro may load the config more than once in a process.
+  if (watcher || process.env.LUCENT_WATCH_CHILD) return;
+  const bin = path.join(__dirname, "../bin/lucent.cjs");
+  // stdin stays Metro's: its keys (r reload, d dev menu) are not ours.
+  watcher = spawn(process.execPath, [bin, "dev", "--compact", "--root", root], {
+    stdio: ["ignore", "inherit", "inherit"],
+    env: { ...process.env, LUCENT_WATCH_CHILD: "1" },
+  });
+  // Ctrl-C reaches the watcher through the process group; this covers the rest.
+  process.on("exit", () => watcher.kill());
+}
+
+module.exports = { withLucent };

package/metro/index.d.ts

@@ -0,0 +1,6 @@
+export interface LucentMetroOptions {
+  /** Rebuild .lucent/native while the dev server runs (default: on for dev servers; LUCENT_WATCH=0/1 overrides). */
+  watch?: boolean;
+}
+
+export declare function withLucent<T extends object>(config: T, options?: LucentMetroOptions): T;