mithril-lynx 0.0.1 → 0.0.3

package/README.md

@@ -2,6 +2,14 @@
 
 Mithril.js rendered through [Lynx](https://lynxjs.org)'s Element PAPI — the core runtime layer of a Mithril-based alternative to [`@lynx-js/react`](https://lynxjs.org/react/).
 
+## Getting started
+
+```bash
+npm create mithril-lynx@latest
+```
+
+Scaffolds a new app via [`create-mithril-lynx`](https://github.com/carlos-sweb/create-mithril-lynx) — pick **Hello World** (a tap-to-animate logo demo, the Mithril analog of Lynx's own React hello-world), **Blank** (a single line of text, nothing else), or **Basic Activity** (two screens wired with `mithril-lynx/navigation`, confirmed working end to end on a real device), in TypeScript or JavaScript. That's the fastest way to a running app; the rest of this README documents the framework itself for once you're inside one.
+
 ## What this package is
 
 `src/lynx-mithril-shim.js` is a contract-complete, line-by-line port of `mithril/render/render.js@2.3.8`: the exact same diff algorithm (`createNode`/`updateNodes`/`updateNode`/keyed-diff-with-LIS/etc.) as upstream Mithril, with every DOM call it makes redirected onto Lynx's Element PAPI (`__CreateView`, `__AppendElement`, `__SetAttribute`, `__SetInlineStyles`, `__AddEventListener`, ...) instead of the browser DOM. See `CONTRACT.md` for the exhaustive, reverse-engineered spec of exactly which DOM surface Mithril's renderer touches — that document is the reference this shim is built and validated against.
@@ -35,7 +43,7 @@ engine.addEventListener("__RenderPage", () => {
 });
 ```
 
-Subsequent UI updates flow through `shim.redraw()` (called automatically by event handlers bound via Mithril's own `on*` attrs, since the shim ports Mithril's `EventDict`/redraw machinery verbatim) — **never plain `m.redraw()`**, which is a no-op in this shim-based architecture.
+Subsequent UI updates flow through `shim.redraw()` — **never plain `m.redraw()`**, which is a no-op in this shim-based architecture, and **never automatically after an `on*` handler either**: every event the shim hands to a handler is normalized with `redraw: false` on purpose (confirmed on real hardware 2026-09-10 — an `ontap` handler that only mutates local main-thread state, with no round trip through a data-channel/renderer-mode push, silently doesn't repaint until `shim.redraw()` is called from inside the handler itself; no error is thrown, since Mithril's own `EventDict.handleEvent` just skips the auto-redraw when `ev.redraw === false`). This is deliberate — a real DOM redraws cheaply enough that auto-redraw-per-event is a reasonable default there; a full Lynx PAPI diff pass on every touch event is not something to default to. `mithril-lynx/navigation`'s `push`/`pop`/`replace` already do this internally (see its source), which is why call sites using only that module never need to think about it.
 
 ## Usage — data-channel mode
 
@@ -206,11 +214,74 @@ Two tiers, matching the real complexity spread in Lynx's own `list` examples:
 
   **Deliberately out of scope for v1** (documented, not silently missing): deferred list items (ReactLynx's `defer`/`isReady` promise dance), `componentAtIndexes` batching, and independent per-item redraw after the initial bind — a bound cell's content is recomputed fresh from `renderItem(index)` only when native calls `componentAtIndex` for it (scroll-driven reuse), not automatically when app state changes.
 
+## Navigation
+
+`mithril-lynx/navigation`'s `createNavigator({ initial, initialAttrs? })` is a stack-based, in-memory screen navigator — deliberately **not** built on `m.route` (see "Known permanent gaps" below: Lynx pages have no URL/History API for `m.route` to hook into). Android's own Activity navigation doesn't need URLs either — it's a plain back-stack — so this is that idea directly, not a URL-shaped abstraction forced onto an environment with no URLs.
+
+```js
+import { createNavigator } from "mithril-lynx/navigation";
+import m from "mithril";
+
+const Home = {
+  view: (vnode) => m("view", { ontap: () => vnode.attrs.nav.push(Details, { id: 42 }) }, [
+    m("text", null, "Go to details"),
+  ]),
+};
+const Details = {
+  view: (vnode) => m("view", { ontap: () => vnode.attrs.nav.pop() }, [
+    m("text", null, "Details for #" + vnode.attrs.id + " — tap to go back"),
+  ]),
+};
+
+const nav = createNavigator({ initial: Home });
+shim.renderToPage(page, m(nav.Navigator)); // main-thread-owned mode
+```
+
+Every screen the navigator renders receives its own `attrs` plus a `nav` prop (`push`/`pop`/`replace`/`canGoBack`/`depth`), so screens don't need to import the navigator instance separately to navigate onward. Only the top of the stack is ever mounted — previous screens are torn down, not kept alive offscreen (matching how most single-activity/single-page navigators behave); a popped screen that needs to remember its own state should keep that state somewhere the app already owns (a module-level store, `background.js`'s data store, etc.), not rely on its own component instance surviving the pop.
+
+Built on `shim.redraw()` alone, so it works unmodified in all three rendering modes (main-thread-owned, data-channel, renderer) — `nav.push()`/`pop()`/`replace()` just trigger whichever redraw mechanism that mode already uses.
+
+**Deliberately out of scope for v1**: screen transition animations (left entirely to the app's own CSS/styling on whatever wraps `nav.Navigator`), and hardware back-button integration (no documented Lynx PAPI hook for it was found — wire a screen's own back-affordance to `nav.pop()` instead, as in the example above).
+
+## Custom fonts
+
+Use a plain CSS `@font-face` rule — not `lynx.addFont()`. That JS API (background-thread-only) is for loading a font dynamically *after* mount, matching [`lynx-family/lynx-examples`](https://github.com/lynx-family/lynx-examples)'s own `examples/text/src/custom_font`, which calls it from `componentDidMount` and re-renders via `setState` once its callback fires. For a font known at build time (the common case), `examples/text/src/font_face` is the pattern to copy — a declarative `@font-face`, no JS:
+
+```css
+@font-face {
+  font-family: "Ubuntu Mono";
+  src: url("./assets/fonts/ubuntu-mono-400.ttf");
+}
+
+@font-face {
+  font-family: "Ubuntu Mono";
+  font-weight: 700;
+  src: url("./assets/fonts/ubuntu-mono-700.ttf");
+}
+
+:root {
+  font-family: "Ubuntu Mono"; /* needs enableCSSInheritance, see below */
+}
+```
+
+Two gotchas, both confirmed on real hardware 2026-09-10:
+
+- **The font file must be `.ttf`, not `.woff2`.** A `.woff2` `@font-face` compiles fine — a valid `url('data:font/woff2;base64,...')` lands in the bundle, no build error, no runtime error — but the native text renderer silently never applies it, even with a maximally-distinctive test font (swapping the default sans-serif for a cursive/marker-style face produced zero visual change). Re-pointing the exact same rule at a `.ttf` of the same font worked immediately, no other change needed. Fontsource-distributed packages only ship woff/woff2; get a `.ttf` from the font's original source instead (e.g. [`google/fonts`](https://github.com/google/fonts) for anything Google-Fonts-hosted).
+- **`font-family` set on `:root` (or any ancestor) does not cascade to descendants by default.** `@lynx-js/config-rsbuild-plugin`'s `pluginLynxConfig()` has an `enableCSSInheritance` option that's off unless set explicitly; without it, only the exact element the property is set on gets it — confirmed by setting `font-family: serif` on `:root` and seeing zero change anywhere in the tree. Turn it on (`pluginLynxConfig({ enableCSSInheritance: true })` in `lynx.config.ts`) to use a single `:root` declaration instead of repeating `font-family` on every class.
+
 ## Known permanent gaps
 
 - `m.trust` / innerHTML vnodes — no Lynx PAPI equivalent to raw innerHTML injection.
 - `m.route` — Lynx pages aren't URL-addressable the way DOM `history` is.
 
+## Known gap, not permanent
+
+- `m.request` — throws (`XMLHttpRequest is not defined`) rather than silently misbehaving: it's hard-wired to a real `XMLHttpRequest`, which doesn't exist in Lynx's JS runtime (neither the main-thread Lepus/QuickJS engine nor the background JS thread). Unlike `m.trust`/`m.route` above, this isn't structural — Lynx does have its own networking primitives — it just hasn't been wrapped in a `$window`-shaped compat layer yet. Use Lynx's own networking API directly (wrapped in a `Promise`, if desired) until this exists.
+
+## Rest of the public `m` API — what's actually used
+
+Beyond hyperscript (`m(...)`) itself, only `m.fragment` and `m.censor` are used as shipped from the real `mithril` package — both are pure data/diff logic with no DOM dependency, so they work unmodified. `m.render`, `m.mount`, and `m.redraw` are never called from the real package at all: `mithril-lynx` has its own equivalents (`shim.renderToPage()`/`shim.render()`/`shim.redraw()`, this README's own "Usage" sections) that target the Lynx Element PAPI instead of the DOM — calling the *real* `m.mount()`/`m.redraw()` does nothing here, since they're wired to `m.render()`'s own DOM-only render path, which this project's apps never invoke.
+
 ## Compat with the plain-JS ecosystem
 
 Mithril was never hooks-based, so — unlike React — there's no special rules-of-hooks compatibility story to build: `m.redraw()` after any state mutation already works with any plain-JS state library (a simple pub/sub store, streams, whatever). Nothing in this package needs to shim a specific state-management library for that reason; if something in the ecosystem doesn't work, it's not because of a hooks-equivalence gap.

package/navigation.d.ts

@@ -0,0 +1,35 @@
+// Ambient declaration for the ESM navigation.js (the file itself is not
+// type-checked; this describes its runtime export shape for TS consumers).
+
+import type { Component, ComponentTypes } from "mithril";
+
+export interface Nav {
+  /** Pushes a new screen onto the stack and redraws. */
+  push(component: ComponentTypes<any, any>, attrs?: Record<string, unknown>): void;
+  /** Replaces the current top screen without growing the stack, and redraws. */
+  replace(component: ComponentTypes<any, any>, attrs?: Record<string, unknown>): void;
+  /** Pops the top screen and redraws. Returns false (a no-op) at the root screen. */
+  pop(): boolean;
+  /** True if pop() would actually pop something (stack depth > 1). */
+  canGoBack(): boolean;
+  /** Current stack depth (1 at the root screen). */
+  depth(): number;
+}
+
+export interface Navigator extends Nav {
+  /** Mithril component that always renders whichever screen is on top of the stack. */
+  Navigator: Component;
+}
+
+export interface CreateNavigatorOptions {
+  /** The root screen, mounted first. */
+  initial: ComponentTypes<any, any>;
+  initialAttrs?: Record<string, unknown>;
+}
+
+/**
+ * Creates a stack-based, in-memory navigator (no m.route, no URLs — see
+ * navigation.js's header comment for why). Every screen the navigator
+ * renders receives its own attrs plus a `nav` prop shaped like {@link Nav}.
+ */
+export function createNavigator(options: CreateNavigatorOptions): Navigator;

package/navigation.js

@@ -0,0 +1,76 @@
+// navigation.js
+//
+// Stack-based, in-memory screen navigation (project plan follow-up, "basic
+// Activity" template support) — deliberately NOT built on m.route. Real
+// `m.route` is hard-wired to the browser's URL/History API (see README.md's
+// "Known permanent gaps"), which has no Lynx equivalent: a Lynx page has no
+// address bar, no back/forward, nothing URL-addressable. Android's own
+// Activity navigation doesn't need URLs either — it's a plain back-stack —
+// so this module ports that idea directly instead of forcing a URL-shaped
+// abstraction onto an environment that has no URLs.
+//
+// Only the top of the stack is ever mounted (previous screens are torn
+// down, not kept alive offscreen) — matching how most single-activity /
+// single-page navigators actually behave, and avoiding the cost of keeping
+// arbitrarily many past screens' DOM trees around. A popped screen that
+// needs to remember its own state should keep that state somewhere the app
+// already owns (a module-level store, background.js's data store, etc.),
+// not rely on the screen's own component instance surviving the pop.
+
+import shim from "./src/lynx-mithril-shim.js";
+import m from "mithril";
+
+/**
+ * Creates a navigator: a stack of {component, attrs} screens, plus a
+ * `Navigator` Mithril component that always renders whichever screen is on
+ * top. Every screen receives its own `attrs` PLUS a `nav` prop (this
+ * navigator's push/pop/replace/canGoBack), so screens don't need to import
+ * the navigator instance separately to navigate onward.
+ */
+export function createNavigator(options) {
+	const { initial, initialAttrs } = options;
+	if (initial == null) throw new Error("mithril-lynx/navigation: createNavigator() requires an `initial` screen");
+
+	const stack = [{ component: initial, attrs: initialAttrs }];
+
+	function top() {
+		return stack[stack.length - 1];
+	}
+
+	function push(component, attrs) {
+		stack.push({ component, attrs });
+		shim.redraw();
+	}
+
+	function replace(component, attrs) {
+		stack[stack.length - 1] = { component, attrs };
+		shim.redraw();
+	}
+
+	/** Returns false (a no-op) at the root screen, true otherwise. */
+	function pop() {
+		if (stack.length <= 1) return false;
+		stack.pop();
+		shim.redraw();
+		return true;
+	}
+
+	function canGoBack() {
+		return stack.length > 1;
+	}
+
+	function depth() {
+		return stack.length;
+	}
+
+	const nav = { push, pop, replace, canGoBack, depth };
+
+	const Navigator = {
+		view() {
+			const { component, attrs } = top();
+			return m(component, Object.assign({}, attrs, { nav }));
+		},
+	};
+
+	return Object.assign({ Navigator }, nav);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mithril-lynx",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Mithril.js rendered through Lynx's Element PAPI — a contract-complete port of mithril/render/render.js@2.3.8 to the Lynx main thread, packaged as a reusable framework.",
   "license": "MIT",
   "type": "module",
@@ -49,6 +49,10 @@
       "types": "./list.d.ts",
       "default": "./list.js"
     },
+    "./navigation": {
+      "types": "./navigation.d.ts",
+      "default": "./navigation.js"
+    },
     "./testing": {
       "types": "./testing.d.ts",
       "default": "./testing.js"
@@ -70,6 +74,8 @@
     "gesture.d.ts",
     "list.js",
     "list.d.ts",
+    "navigation.js",
+    "navigation.d.ts",
     "testing.js",
     "testing.d.ts",
     "CONTRACT.md"