@lingxia/skill 0.8.0

package/skill/examples/hello-host-js/README.md

@@ -0,0 +1,25 @@
+# hello-host-js — Shape B: native host app with **JS Logic** lxapp
+
+A macOS host shell that boots, opens one window, and renders an embedded "home" lxapp inside it. The home lxapp's Logic is **JavaScript** (`Page({})` in `index.ts`); the host compiles in the JS AppService runtime (`features.appService: true`). No Rust route — the View can still call Rust if you add one, but this example keeps the slate clean to focus on the host ↔ JS-lxapp wiring.
+
+For the **Rust Logic** variant (no JS runtime, HTML-only view, `#[lingxia::native]` doing all the work), see [`../hello-host-rust/`](../hello-host-rust/README.md). The two examples differ only on the JS vs Rust Logic split; the host wiring is the same.
+
+This is what `lingxia new my-app -t native-app -p macos --package-id com.example.my-app -y` produces in a minimal form. Real scaffolding adds platform-specific subdirectories under `macos/`, generated icons, and CI scripts; those are reproducible from this `lingxia.yaml` and not shown here.
+
+Files:
+
+- `lingxia.yaml` — host project source of truth: app metadata, target platform(s), feature flags, bundled lxapp sources, App UI (surfaces + activators).
+- `home/` — the embedded "home" lxapp this host opens by default (same JS-Logic shape as [`../hello-lxapp/`](../hello-lxapp/README.md) — see that example for page Logic + View detail).
+
+What to study:
+
+- `app.homeAppId` matches `resources.bundles[].appId` matches the embedded `lxapp.json.appId`. **All three must agree** or the build fails / the wrong app launches.
+- `ui.surfaces[].content.appId` points at the same `homeAppId` — that's what fills the macOS window.
+- `features.appService: true` enables the JS Logic runtime. **Required** because the embedded lxapp has a `.ts` Logic file. (For the opposite case, see `../hello-host-rust/`.)
+
+Cross-references:
+
+- `lingxia.yaml` full reference (every field, every section): [`../../app/project.md`](../../app/project.md)
+- macOS App UI (surfaces, activators, attach panels, menu-bar): [`../../app/project.md#macos-app-ui`](../../app/project.md#macos-app-ui)
+- Apple SDK startup APIs (`Lingxia.quickStart()`): [`../../app/apple-sdk.md`](../../app/apple-sdk.md)
+- Sibling Shape C example (Rust Logic): [`../hello-host-rust/`](../hello-host-rust/README.md)

package/skill/examples/hello-host-js/home/lxapp.json

@@ -0,0 +1,12 @@
+{
+  "appId": "hello-home",
+  "version": "0.1.0",
+  "appName": "Hello Home",
+  "pages": [
+    { "name": "home", "path": "pages/home/index" }
+  ],
+  "security": {
+    "network": { "trustedDomains": [] },
+    "privileges": []
+  }
+}

package/skill/examples/hello-host-js/home/pages/home/index.json

@@ -0,0 +1,4 @@
+{
+  "navigationBarTitleText": "Hello",
+  "navigationStyle": "default"
+}

package/skill/examples/hello-host-js/home/pages/home/index.ts

@@ -0,0 +1,14 @@
+// Logic for the embedded home lxapp. Identical shape to ../hello-lxapp.
+// The host shell opens this page via ui.launch.initialSurface -> surface
+// -> content.appId -> lxapp.json.pages[0].
+
+interface HomeData {
+  count: number;
+}
+
+Page<HomeData>({
+  data: { count: 0 },
+  increment() {
+    this.setData({ count: this.data.count + 1 });
+  },
+});

package/skill/examples/hello-host-js/home/pages/home/index.tsx

@@ -0,0 +1,15 @@
+import { useLxPage } from "@lingxia/react";
+
+type PageData = { count: number };
+type PageActions = { increment: () => void };
+
+export default function HomePage() {
+  const { data, actions } = useLxPage<PageData, PageActions>();
+  return (
+    <main style={{ padding: 24 }}>
+      <h1>Hello from the host app</h1>
+      <p>Count: {data.count}</p>
+      <button onClick={() => actions.increment()}>+1</button>
+    </main>
+  );
+}

package/skill/examples/hello-host-js/lingxia.yaml

@@ -0,0 +1,39 @@
+# Host app project config. The source of truth for the macOS build.
+# `lingxia build` regenerates app.json + ui.json from this file; do not
+# edit the generated files directly.
+
+app:
+  projectName: hello-host
+  productName: Hello Host
+  productVersion: 0.1.0
+  platforms: [macos]
+  homeAppId: hello-home   # must match resources.bundles[].appId below
+
+macos:
+  bundleId: com.example.hello-host
+  deploymentTarget: "12.0"
+  targetName: HelloHost
+  executableName: HelloHost
+
+features:
+  appService: true    # the embedded lxapp uses JS Logic, so AppService must be on
+  shell: false
+  devtools: false
+
+resources:
+  bundles:
+    - type: lxapp
+      appId: hello-home   # same string as app.homeAppId
+      path: home          # local directory containing lxapp.json + pages/
+
+ui:
+  launch:
+    initialSurface: main
+  surfaces:
+    - id: main
+      presentation:
+        kind: window
+      content:
+        kind: lxapp
+        appId: hello-home   # same id again — what to render inside the surface
+  activators: []

package/skill/examples/hello-host-rust/Cargo.toml

@@ -0,0 +1,15 @@
+# Minimal host crate. `lingxia new` emits a workspace; this snippet shows
+# only the slot that contains #[lingxia::native] routes and HostAddon.
+
+[package]
+name = "hello-native"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[dependencies]
+lingxia = "0.7"
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["rt", "macros", "time"] }

package/skill/examples/hello-host-rust/README.md

@@ -0,0 +1,44 @@
+# hello-host-rust — Shape C: host app with **Rust Logic, no JS runtime**
+
+A native host app whose embedded home lxapp is **HTML-only and has no JS Logic layer**. All state and behavior live in the Rust crate, exposed to the View through `#[lingxia::native]` routes. The JS AppService runtime is not even compiled into the host (`features.appService: false`).
+
+Pick this shape for: menu-bar utilities, system-tray tools, Rust-heavy desktop apps where the UI is mostly a thin view over native logic.
+
+## Contrast with [`../hello-host-js/`](../hello-host-js/README.md)
+
+Same host shell, opposite Logic side:
+
+| | `hello-host-js` (Shape B) | `hello-host-rust` (Shape C) |
+|---|---|---|
+| `features.appService` | `true` | **`false`** |
+| `lxapp.json.logic` | (omitted, defaults true) | **`false`** |
+| Logic layer | `Page({ data, …actions })` in `index.ts` | **Rust** `#[lingxia::native]` routes |
+| View | React `index.tsx` + `useLxPage` | **plain `index.html` + `<script>`** |
+| Bridge surface | `actions.foo()` from `useLxPage()` | `window.native.foo(...)` (CLI-generated browser global) |
+| JS AppService runtime in host binary | ✅ shipped | **❌ not compiled in** (smaller binary) |
+| Cargo dep on `lingxia` | optional | **required** |
+
+The host project shape (`lingxia.yaml` `ui`, `resources.bundles`, FFI export) is identical. Only the lxapp's authoring model and the `features.appService` switch differ.
+
+## Files
+
+- `lingxia.yaml` — `features.appService: false`; everything else like hello-host-js.
+- `Cargo.toml` — host Rust crate declaration.
+- `src/lib.rs` — `#[lingxia::native("greet.hello")]` route + `HostAddon` + platform FFI export. (Same shape as a Shape B route — the route signature doesn't change between B and C.)
+- `home/lxapp.json` — has `"logic": false` flag; the runtime won't try to spin up a JS Logic layer.
+- `home/pages/home/index.html` — the entire UI. `<script src="lingxia://lxapp/.lingxia/native.js">` auto-loads the CLI-generated client; the click handler calls `window.native.greet.hello(...)`.
+- `home/pages/home/index.json` — page-level config (navigation bar). The same shape works for both B and C.
+
+## What to study
+
+- **`features.appService: false`** disables the JS runtime. A logic-enabled lxapp (no `"logic": false`) paired with this is **rejected at startup** — flip both together.
+- **`"logic": false`** in `lxapp.json` is the lxapp-side declaration that there is no `Page({})` Logic. The CLI build won't look for `pages/*/index.ts` files; the page is the `index.html`.
+- **No `@lingxia/react` / `@lingxia/vue` / `@lingxia/html`** dependency. Those packages all assume the AppService bridge (`Page({})` shape). Use plain DOM APIs.
+- **`window.native.*`** is the CLI-generated **browser-global** client (different output format from the `@lingxia/native` module client used by React/Vue Shape B). The HTML view just `<script>`-loads it; no bundler involved.
+- **The Rust route is identical** to a Shape B route — `#[lingxia::native]`, `HostAddon::install_host_apis`, the macro-generated `<fn>_host()` companion. Only which side owns Logic differs.
+
+## Cross-references in this skill
+
+- Full native Rust development (streams, channels, facades, `lingxia::js` extensions, Android/Harmony FFI): [`../../native/development.md`](../../native/development.md)
+- `lingxia.yaml` full reference including the `features` section: [`../../app/project.md`](../../app/project.md)
+- Sibling Shape B example: [`../hello-host-js/`](../hello-host-js/README.md)

package/skill/examples/hello-host-rust/home/lxapp.json

@@ -0,0 +1,13 @@
+{
+  "appId": "hello-home",
+  "version": "0.1.0",
+  "appName": "Hello Host (Rust Logic)",
+  "logic": false,
+  "pages": [
+    { "name": "home", "path": "pages/home/index" }
+  ],
+  "security": {
+    "network": { "trustedDomains": [] },
+    "privileges": []
+  }
+}

package/skill/examples/hello-host-rust/home/pages/home/index.html

@@ -0,0 +1,46 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Hello Host (Rust Logic)</title>
+    <!--
+      Shape C: no @lingxia/html, no Page({}), no useLxPage.
+      The runtime auto-injects the CLI-generated native client at
+      lingxia://lxapp/.lingxia/native.js, exposing `window.native.*`.
+      All state and "Logic" live in the Rust crate at ../../../src/lib.rs.
+    -->
+    <script src="lingxia://lxapp/.lingxia/native.js"></script>
+    <style>
+      body { font-family: system-ui; padding: 24px; }
+      button { font-size: 16px; padding: 8px 16px; }
+      #out { margin-top: 16px; font-size: 18px; }
+    </style>
+  </head>
+  <body>
+    <h1>Hello Host (Rust Logic)</h1>
+    <button id="say">Call greet.hello</button>
+    <p id="out"></p>
+
+    <script>
+      const btn = document.getElementById("say");
+      const out = document.getElementById("out");
+
+      btn.addEventListener("click", async () => {
+        btn.disabled = true;
+        btn.textContent = "Calling Rust…";
+        try {
+          // window.native is the CLI-generated browser-global client.
+          // Each #[lingxia::native("ns.method")] route becomes
+          // window.native.ns.method(...).
+          const res = await window.native.greet.hello({ name: "World" });
+          out.textContent = res.greeting;
+        } catch (err) {
+          out.textContent = `Error: ${err && err.message ? err.message : err}`;
+        } finally {
+          btn.disabled = false;
+          btn.textContent = "Call greet.hello";
+        }
+      });
+    </script>
+  </body>
+</html>

package/skill/examples/hello-host-rust/home/pages/home/index.json

@@ -0,0 +1,4 @@
+{
+  "navigationBarTitleText": "Hello Native",
+  "navigationStyle": "default"
+}

package/skill/examples/hello-host-rust/lingxia.yaml

@@ -0,0 +1,32 @@
+app:
+  projectName: hello-host-rust
+  productName: Hello Host (Rust Logic)
+  productVersion: 0.1.0
+  platforms: [macos]
+  homeAppId: hello-home
+
+macos:
+  bundleId: com.example.hello-host-rust
+  deploymentTarget: "12.0"
+  targetName: HelloHostRust
+  executableName: HelloHostRust
+
+features:
+  appService: false   # Shape C: no JS AppService runtime. All Logic lives in Rust.
+  shell: false
+  devtools: false
+
+resources:
+  bundles:
+    - type: lxapp
+      appId: hello-home
+      path: home
+
+ui:
+  launch:
+    initialSurface: main
+  surfaces:
+    - id: main
+      presentation: { kind: window }
+      content: { kind: lxapp, appId: hello-home }
+  activators: []

package/skill/examples/hello-host-rust/src/lib.rs

@@ -0,0 +1,58 @@
+// Host Rust library. Exposes one route to the View via #[lingxia::native].
+//
+// The macro generates a sibling fn `<name>_host()` that returns the
+// host-entry registration value — you do NOT write that fn yourself, and
+// you cannot rename it.
+
+use std::sync::Arc;
+
+#[derive(serde::Deserialize)]
+struct HelloInput {
+    name: String,
+}
+
+#[derive(serde::Serialize)]
+struct HelloOutput {
+    greeting: String,
+}
+
+// Parameter ordering — enforced by the macro:
+//   1. `Arc<lingxia::LxApp>`         (optional, must be FIRST when present)
+//   2. JSON payload (any serde::Deserialize type)  (optional)
+//   3. `lingxia::host::HostCancel`   (optional, must be LAST when present)
+//
+// Return type must be `lingxia::Result<T>` where T: serde::Serialize.
+#[lingxia::native("greet.hello")]
+async fn greet_hello(
+    _app: Arc<lingxia::LxApp>,
+    input: HelloInput,
+) -> lingxia::Result<HelloOutput> {
+    Ok(HelloOutput {
+        greeting: format!("Hello, {}!", input.name),
+    })
+}
+
+struct AppHostAddon;
+
+impl lingxia::HostAddon for AppHostAddon {
+    fn install_host_apis(&self) {
+        // greet_hello_host() is generated by the #[lingxia::native] macro
+        // applied to `greet_hello` above. Register one per route.
+        lingxia::host::register_host_entry(greet_hello_host());
+    }
+
+    fn start_services(&self) {
+        // Background services go here (devtool bridge, push, ipc, …).
+        // None in this example.
+    }
+}
+
+// Platform FFI export. Apple platforms call this symbol from the SDK at
+// startup. Android uses a `Java_<package>_<class>_nativeRegisterHostAddon`
+// JNI entrypoint; Harmony uses a `#[napi]`-annotated function. See the
+// skill's native/development.md for the full set.
+#[cfg(any(target_os = "ios", target_os = "macos"))]
+#[unsafe(no_mangle)]
+pub extern "C" fn lingxia_register_host_addon() {
+    lingxia::register_host_addon(Box::new(AppHostAddon));
+}

package/skill/examples/hello-lxapp/README.md

@@ -0,0 +1,29 @@
+# hello-lxapp — Shape A: a standalone lxapp
+
+A page-based mini-app. Runs in any LingXia host (e.g. macOS Runner via `lingxia dev`). No native shell, no Rust.
+
+This is the smallest meaningful starter. **Read it; don't copy-paste it whole** — scaffold a real project with `lingxia new my-app -t lxapp -y` and refer back here for shape.
+
+Files:
+
+- `lxapp.json` — appId, version, pages list, security policy
+- `lxapp.config.ts` — build config (view framework, static dirs, …)
+- `package.json` — runtime + dev deps you actually need
+- `pages/home/`
+  - `index.ts` — **Logic** (`Page({…})`) — state and actions, runs in the native JS runtime
+  - `index.tsx` — **View** (React + `useLxPage`) — renders UI, runs in the WebView
+  - `index.json` — page-level config (navigation bar, etc.)
+
+What to study:
+
+- How **Logic** initializes `data: {…}` and exposes public methods to View.
+- How `_privateHelper` is hidden from View by the `_` prefix convention.
+- How **View** types `PageData` / `PageActions` with **required** fields (the runtime guarantees first-paint data and wired-up actions).
+- How `lxapp.json.security.network.trustedDomains` is set to `[]` to deny all external `fetch()` calls — flip to actual hostnames before running anything that talks to a server.
+
+Cross-references in this skill:
+
+- Full page authoring: [`../../lxapp/guide.md`](../../lxapp/guide.md)
+- Bridge mechanics (`setData`, stream, channel): [`../../lxapp/bridge.md`](../../lxapp/bridge.md)
+- Native components (`LxInput`, `LxVideo`, …): [`../../lxapp/components.md`](../../lxapp/components.md)
+- Logic-side `lx.*` API: [`../../lxapp/lx-api.md`](../../lxapp/lx-api.md)

package/skill/examples/hello-lxapp/lxapp.config.ts

@@ -0,0 +1,8 @@
+// LxApp build config. Loaded by `lingxia build` / `lingxia dev`.
+// View framework is auto-detected from page file extensions (.tsx → react,
+// .vue → vue, .html → html). `staticDirs` declares root folders copied
+// verbatim into dist/.
+export default {
+  view: { framework: "react" },
+  staticDirs: ["public"],
+};

package/skill/examples/hello-lxapp/lxapp.json

@@ -0,0 +1,14 @@
+{
+  "appId": "hello-lxapp",
+  "version": "0.1.0",
+  "appName": "Hello LxApp",
+  "pages": [
+    { "name": "home", "path": "pages/home/index" }
+  ],
+  "security": {
+    "network": {
+      "trustedDomains": []
+    },
+    "privileges": []
+  }
+}

package/skill/examples/hello-lxapp/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "hello-lxapp",
+  "version": "0.1.0",
+  "private": true,
+  "dependencies": {
+    "@lingxia/react": "^0.7.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@lingxia/types": "^0.7.0",
+    "typescript": "^5.3.0"
+  }
+}

package/skill/examples/hello-lxapp/pages/home/index.json

@@ -0,0 +1,4 @@
+{
+  "navigationBarTitleText": "Home",
+  "navigationStyle": "default"
+}

package/skill/examples/hello-lxapp/pages/home/index.ts

@@ -0,0 +1,35 @@
+// Logic layer. Runs in the native JS runtime (not the WebView).
+// `Page` is a global from @lingxia/types — no import needed.
+// `_`-prefixed methods are private to Logic and NOT exposed as View actions.
+
+interface HomeData {
+  count: number;
+  message: string;
+}
+
+Page<HomeData>({
+  data: {
+    count: 0,
+    message: "Tap to increment",
+  },
+
+  onLoad(options) {
+    // `options` is the URL query that opened this page.
+    // Useful for routing — ignored in the simplest case.
+  },
+
+  increment() {
+    // `this.data` is read-only. Always go through `setData` so the View
+    // sees the change.
+    this.setData({ count: this.data.count + 1 });
+  },
+
+  reset() {
+    this.setData({ count: 0 });
+  },
+
+  _doubled() {
+    // Private helper. Not visible to View.
+    return this.data.count * 2;
+  },
+});

package/skill/examples/hello-lxapp/pages/home/index.tsx

@@ -0,0 +1,34 @@
+// View layer. Runs in the WebView.
+// `useLxPage` returns `{ data, actions }` — data is reactive, actions
+// are bridge functions wired to the public methods on Page({}).
+//
+// Type fields as REQUIRED unless your Logic actually populates them
+// lazily — the runtime guarantees both `data` and `actions` are wired
+// by first paint. All-optional types create `?.()` and `??` noise.
+import { useLxPage } from "@lingxia/react";
+
+type PageData = {
+  count: number;
+  message: string;
+};
+
+type PageActions = {
+  increment: () => void;
+  reset: () => void;
+};
+
+export default function HomePage() {
+  const { data, actions } = useLxPage<PageData, PageActions>();
+
+  return (
+    <main style={{ padding: 24, fontFamily: "system-ui" }}>
+      <h1>Hello LxApp</h1>
+      <p>{data.message}</p>
+      <p style={{ fontSize: 48 }}>{data.count}</p>
+      <button onClick={() => actions.increment()}>+1</button>
+      <button onClick={() => actions.reset()} style={{ marginLeft: 8 }}>
+        Reset
+      </button>
+    </main>
+  );
+}