lynx-console 0.3.0 → 0.4.0

package/README.md

@@ -1,16 +1,37 @@
+[한국어](https://github.com/daangn/lynx-console/blob/main/package/README_ko.md) | English
+
 # lynx-console
 
 An in-app developer console that can be embedded in Lynx apps. View console logs, network requests, and performance metrics in real time.
 
+## Demo
+
+https://github.com/user-attachments/assets/dcd874bf-ff2e-4a98-ae03-d83de5fae31c
+
+<img width="450" height="450" alt="lynx_bundle_qrcode_fullscreen" src="https://github.com/user-attachments/assets/8bbb9bfe-df2b-436d-ad17-6e4eb4b672c9" />
+
+Scan the QR code above with the [Lynx Explorer](https://lynxjs.org/guide/start/quick-start.html#via-lynx-explorer-app) app to try the demo.
+
 ## Features
 
-- **Console Logs** — View output from `console.log`, `console.error`, and more in real time
-- **Main Thread Console** — Capture logs from the main thread
-- **Network Monitor** — Inspect method, headers, body, and response of `fetch` requests
-- **Performance Monitor** — Track performance metrics such as FCP (First Contentful Paint)
-- **Floating Button** — Open and close the console with a floating button that displays the FCP value
+- **Console Logs** — View output from `console.log`, `console.error`, and more in real time. Supports level filtering, keyword search, log clearing, and a built-in REPL
+- **Main Thread Console** — Capture logs from the main thread alongside background thread logs
+
+https://github.com/user-attachments/assets/539fe31a-aca4-468d-b673-3b070b21cd08
+
+- **Network Monitor** — Inspect method, status, headers, request body, and response of `fetch` requests
+
+https://github.com/user-attachments/assets/edda4778-ab8d-4cb9-a3c5-bd8c42c81bde
+
+- **Performance Monitor** — Track FCP (First Contentful Paint) and other performance metrics with raw entry details
+
+https://github.com/user-attachments/assets/d231bdf5-71bb-483f-9bdb-5843279c1308
+
+- **Floating Button** — Displays the latest FCP value; tap to open the console, long-press and drag to reposition it
+- **Resizable Panel** — Drag the handle to resize the console panel (200–700px); swipe down to dismiss
+- **Tab Visibility** — Only tabs for initialized monitors are shown; uninitialized monitors are automatically hidden
+- **Custom Tabs** — Add your own tabs to the console via the `customTabs` prop
 - **Light/Dark Theme** support
-- **Seed Design** based UI
 
 ## Installation
 
@@ -22,10 +43,29 @@ yarn add lynx-console
 
 ```bash
 yarn add @lynx-js/react @lynx-js/types
+yarn add -D @types/react
 ```
 
+> **Note:** Each monitor requires the corresponding Lynx API to be available at runtime. If `lynx.fetch` is not present, `initNetworkMonitor()` will be skipped with a warning. Likewise, `initPerformanceMonitor()` requires `lynx.performance`.
+
 ## Usage
 
+### 0. Configure Build (Required for iOS)
+
+On iOS, the Lynx runtime (JSC) injects a separate `console` object that is different from `globalThis.console`. This means patches applied by `initLogMonitor()` won't take effect on iOS unless you explicitly replace the `console` identifier with `globalThis.console` at build time.
+
+Add the following to your `lynx.config.ts`:
+
+```typescript
+export default defineConfig({
+  source: {
+    define: {
+      console: "globalThis.console",
+    },
+  },
+});
+```
+
 ### 1. Initialize Monitors
 
 Call the monitoring functions at your app's entry point. This setup must run **before** the `LynxConsole` component is rendered.
@@ -44,6 +84,8 @@ initNetworkMonitor();
 initPerformanceMonitor();
 ```
 
+> **Note:** `initLogMonitor()` must be called before `initMainThreadConsole()`, as the main thread console depends on the log monitor being initialized first.
+
 ### 2. Render the Component
 
 ```tsx
@@ -68,7 +110,31 @@ function App() {
       {/* Your app content */}
       <Suspense>
         <LynxConsole theme="light" safeAreaInsetBottom="34px" />
-      <Suspense>
+      </Suspense>
+    </view>
+  );
+}
+```
+
+### Adding Custom Tabs
+
+You can add your own tabs to the console using the `customTabs` prop.
+
+```tsx
+import LynxConsole, { type CustomTab } from "lynx-console";
+
+const customTabs: CustomTab[] = [
+  {
+    key: "debug",
+    label: "Debug",
+    renderContent: () => <text>Custom debug content</text>,
+  },
+];
+
+function App() {
+  return (
+    <view>
+      <LynxConsole customTabs={customTabs} />
     </view>
   );
 }
@@ -99,34 +165,45 @@ function App() {
     <view>
       <Suspense>
         <LynxConsole ref={consoleRef} />
-      <Suspense>
+      </Suspense>
     </view>
   );
 }
 ```
 
+You can also integrate it with a back press handler so that the console closes when the back button is pressed.
+
 ## API
 
 ### `LynxConsole` Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `theme` | `"light" \| "dark"` | `"light"` | Console UI theme |
-| `safeAreaInsetBottom` | `string` | `"50px"` | Bottom safe area inset |
+| Prop                  | Type                | Default     | Description                                      |
+| --------------------- | ------------------- | ----------- | ------------------------------------------------ |
+| `theme`               | `"light" \| "dark"` | `"light"`   | Console UI theme                                 |
+| `safeAreaInsetBottom` | `string`            | `"50px"`    | Bottom safe area inset                           |
+| `customTabs`          | `CustomTab[]`       | `undefined` | Additional custom tabs to display in the console |
+
+### `CustomTab`
+
+| Property        | Type              | Description                           |
+| --------------- | ----------------- | ------------------------------------- |
+| `key`           | `string`          | Unique identifier for the tab         |
+| `label`         | `string`          | Tab label text                        |
+| `renderContent` | `() => ReactNode` | Function that renders the tab content |
 
 ### `LynxConsoleHandle`
 
-| Method | Description |
-|--------|-------------|
-| `open()` | Opens the console |
-| `close()` | Closes the console |
+| Method     | Description                         |
+| ---------- | ----------------------------------- |
+| `open()`   | Opens the console                   |
+| `close()`  | Closes the console                  |
 | `isOpen()` | Returns whether the console is open |
 
 ### Monitor Initialization Functions
 
-| Function | Description |
-|----------|-------------|
-| `initLogMonitor()` | Captures `console.log`, `console.error`, etc. |
-| `initMainThreadConsole()` | Captures console output from the main thread |
-| `initNetworkMonitor()` | Intercepts and records `fetch` requests |
-| `initPerformanceMonitor()` | Collects performance metrics |
+| Function                   | Description                                   |
+| -------------------------- | --------------------------------------------- |
+| `initLogMonitor()`         | Captures `console.log`, `console.error`, etc. |
+| `initMainThreadConsole()`  | Captures console output from the main thread  |
+| `initNetworkMonitor()`     | Intercepts and records `fetch` requests       |
+| `initPerformanceMonitor()` | Collects performance metrics                  |

package/dist/index.cjs

@@ -270,6 +270,102 @@ const usePerformance = () => {
 	};
 };
 
+//#endregion
+//#region src/utils/parseCssStyle.ts
+const DANGEROUS_VALUE = /url\s*\(|expression\s*\(|@import/i;
+const toCamelCase = (name) => {
+	if (name.startsWith("--")) return name;
+	return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+};
+const parseCssString = (css) => {
+	const result = {};
+	for (const raw of css.split(";")) {
+		const decl = raw.trim();
+		if (!decl) continue;
+		const colon = decl.indexOf(":");
+		if (colon <= 0) continue;
+		const name = decl.slice(0, colon).trim().toLowerCase();
+		const value = decl.slice(colon + 1).trim();
+		if (!name || !value) continue;
+		if (DANGEROUS_VALUE.test(value)) continue;
+		result[toCamelCase(name)] = value;
+	}
+	return result;
+};
+
+//#endregion
+//#region src/utils/parseFormat.ts
+const HAS_FORMAT = /%[csdifoO%]/;
+const formatNumber = (v, int) => {
+	const n = typeof v === "number" ? int ? Math.trunc(v) : v : typeof v === "symbol" ? NaN : int ? parseInt(String(v), 10) : parseFloat(String(v));
+	return Number.isNaN(n) ? "NaN" : String(n);
+};
+const parseConsoleArgs = (args) => {
+	const first = args[0];
+	if (typeof first !== "string" || !HAS_FORMAT.test(first)) return {
+		segments: [],
+		rest: args
+	};
+	const segments = [];
+	let currentText = "";
+	let currentStyle;
+	let argIndex = 1;
+	let lastIndex = 0;
+	const flushText = () => {
+		if (currentText) {
+			segments.push({
+				type: "text",
+				text: currentText,
+				style: currentStyle
+			});
+			currentText = "";
+		}
+	};
+	const re = /%([csdifoO%])/g;
+	let match = re.exec(first);
+	while (match !== null) {
+		currentText += first.slice(lastIndex, match.index);
+		lastIndex = re.lastIndex;
+		const spec = match[1];
+		if (spec === "%") currentText += "%";
+		else if (argIndex >= args.length) currentText += match[0];
+		else {
+			const arg = args[argIndex++];
+			switch (spec) {
+				case "c":
+					flushText();
+					currentStyle = typeof arg === "string" ? parseCssString(arg) : void 0;
+					break;
+				case "s":
+					currentText += String(arg);
+					break;
+				case "d":
+				case "i":
+					currentText += formatNumber(arg, true);
+					break;
+				case "f":
+					currentText += formatNumber(arg, false);
+					break;
+				case "o":
+				case "O":
+					flushText();
+					segments.push({
+						type: "arg",
+						value: arg
+					});
+					break;
+			}
+		}
+		match = re.exec(first);
+	}
+	currentText += first.slice(lastIndex);
+	flushText();
+	return {
+		segments,
+		rest: args.slice(argIndex)
+	};
+};
+
 //#endregion
 //#region src/components/LogPanel.tsx
 const LOG_LEVELS = [
@@ -400,7 +496,6 @@ const LogPanel = ({ logs, clearLogs }) => {
 			params: { value: "" }
 		}).exec();
 		runCode(trimmed);
-		setTimeout(() => scrollToBottom(false), 100);
 	};
 	const renderArg = (arg, parentKey, level) => {
 		const key = parentKey;
@@ -601,9 +696,31 @@ const LogPanel = ({ logs, clearLogs }) => {
                     </text>
                   </view>
                   <view className={"cp-logArgsContainer"}>
-                    {log.args.map((arg, index) => <view key={`${log.id}-${index.toString()}`} className={"cp-logArgItem"} style={{ fontWeight: fontWeight.regular }}>
-                        {renderArg(arg, `${log.id}-${index.toString()}`, log.level)}
-                      </view>)}
+                    {(() => {
+			const { segments, rest } = parseConsoleArgs(log.args);
+			const baseTextStyle = {
+				color: getStringColor(colors, log.level),
+				fontWeight: fontWeight.regular
+			};
+			const wrap = (key, content) => <view key={key} className={"cp-logArgItem"} style={{ fontWeight: fontWeight.regular }}>
+                          {content}
+                        </view>;
+			return <>
+                          {segments.map((seg, index) => {
+				const key = `${log.id}-seg-${index.toString()}`;
+				return wrap(key, seg.type === "text" ? <text className={"cp-argString t3"} style={{
+					...baseTextStyle,
+					...seg.style
+				}}>
+                                  {seg.text}
+                                </text> : renderArg(seg.value, key, log.level));
+			})}
+                          {rest.map((arg, index) => {
+				const key = `${log.id}-rest-${index.toString()}`;
+				return wrap(key, renderArg(arg, key, log.level));
+			})}
+                        </>;
+		})()}
                   </view>
                 </view>
               </list-item>;

package/dist/index.mjs

@@ -270,6 +270,102 @@ const usePerformance = () => {
 	};
 };
 
+//#endregion
+//#region src/utils/parseCssStyle.ts
+const DANGEROUS_VALUE = /url\s*\(|expression\s*\(|@import/i;
+const toCamelCase = (name) => {
+	if (name.startsWith("--")) return name;
+	return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+};
+const parseCssString = (css) => {
+	const result = {};
+	for (const raw of css.split(";")) {
+		const decl = raw.trim();
+		if (!decl) continue;
+		const colon = decl.indexOf(":");
+		if (colon <= 0) continue;
+		const name = decl.slice(0, colon).trim().toLowerCase();
+		const value = decl.slice(colon + 1).trim();
+		if (!name || !value) continue;
+		if (DANGEROUS_VALUE.test(value)) continue;
+		result[toCamelCase(name)] = value;
+	}
+	return result;
+};
+
+//#endregion
+//#region src/utils/parseFormat.ts
+const HAS_FORMAT = /%[csdifoO%]/;
+const formatNumber = (v, int) => {
+	const n = typeof v === "number" ? int ? Math.trunc(v) : v : typeof v === "symbol" ? NaN : int ? parseInt(String(v), 10) : parseFloat(String(v));
+	return Number.isNaN(n) ? "NaN" : String(n);
+};
+const parseConsoleArgs = (args) => {
+	const first = args[0];
+	if (typeof first !== "string" || !HAS_FORMAT.test(first)) return {
+		segments: [],
+		rest: args
+	};
+	const segments = [];
+	let currentText = "";
+	let currentStyle;
+	let argIndex = 1;
+	let lastIndex = 0;
+	const flushText = () => {
+		if (currentText) {
+			segments.push({
+				type: "text",
+				text: currentText,
+				style: currentStyle
+			});
+			currentText = "";
+		}
+	};
+	const re = /%([csdifoO%])/g;
+	let match = re.exec(first);
+	while (match !== null) {
+		currentText += first.slice(lastIndex, match.index);
+		lastIndex = re.lastIndex;
+		const spec = match[1];
+		if (spec === "%") currentText += "%";
+		else if (argIndex >= args.length) currentText += match[0];
+		else {
+			const arg = args[argIndex++];
+			switch (spec) {
+				case "c":
+					flushText();
+					currentStyle = typeof arg === "string" ? parseCssString(arg) : void 0;
+					break;
+				case "s":
+					currentText += String(arg);
+					break;
+				case "d":
+				case "i":
+					currentText += formatNumber(arg, true);
+					break;
+				case "f":
+					currentText += formatNumber(arg, false);
+					break;
+				case "o":
+				case "O":
+					flushText();
+					segments.push({
+						type: "arg",
+						value: arg
+					});
+					break;
+			}
+		}
+		match = re.exec(first);
+	}
+	currentText += first.slice(lastIndex);
+	flushText();
+	return {
+		segments,
+		rest: args.slice(argIndex)
+	};
+};
+
 //#endregion
 //#region src/components/LogPanel.tsx
 const LOG_LEVELS = [
@@ -400,7 +496,6 @@ const LogPanel = ({ logs, clearLogs }) => {
 			params: { value: "" }
 		}).exec();
 		runCode(trimmed);
-		setTimeout(() => scrollToBottom(false), 100);
 	};
 	const renderArg = (arg, parentKey, level) => {
 		const key = parentKey;
@@ -601,9 +696,31 @@ const LogPanel = ({ logs, clearLogs }) => {
                     </text>
                   </view>
                   <view className={"cp-logArgsContainer"}>
-                    {log.args.map((arg, index) => <view key={`${log.id}-${index.toString()}`} className={"cp-logArgItem"} style={{ fontWeight: fontWeight.regular }}>
-                        {renderArg(arg, `${log.id}-${index.toString()}`, log.level)}
-                      </view>)}
+                    {(() => {
+			const { segments, rest } = parseConsoleArgs(log.args);
+			const baseTextStyle = {
+				color: getStringColor(colors, log.level),
+				fontWeight: fontWeight.regular
+			};
+			const wrap = (key, content) => <view key={key} className={"cp-logArgItem"} style={{ fontWeight: fontWeight.regular }}>
+                          {content}
+                        </view>;
+			return <>
+                          {segments.map((seg, index) => {
+				const key = `${log.id}-seg-${index.toString()}`;
+				return wrap(key, seg.type === "text" ? <text className={"cp-argString t3"} style={{
+					...baseTextStyle,
+					...seg.style
+				}}>
+                                  {seg.text}
+                                </text> : renderArg(seg.value, key, log.level));
+			})}
+                          {rest.map((arg, index) => {
+				const key = `${log.id}-rest-${index.toString()}`;
+				return wrap(key, renderArg(arg, key, log.level));
+			})}
+                        </>;
+		})()}
                   </view>
                 </view>
               </list-item>;