create-eventus-app 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-eventus-app",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Scaffold an Eventus mini app.",
   "type": "module",
   "bin": {

package/template/README.md

@@ -15,6 +15,12 @@ pnpm dev
 - `pnpm build`: type-check and build the app
 - `pnpm preview`: preview the production build locally
 
+## Local Live Preview
+
+Run `pnpm dev`, open the app in your desktop browser, and scan the QR code from
+Eventus X using the `Developer` screen. Your phone and computer must be on the
+same local network for the live preview URL to be reachable.
+
 ## Eventus Files
 
 - `eventus.manifest.json`: base Eventus manifest consumed by the Vite plugin

package/template/package.json

@@ -10,10 +10,12 @@
   },
   "dependencies": {
     "@eventusgo/sdk": "__EVENTUS_SDK_VERSION__",
+    "qrcode": "1.5.4",
     "react": "18.3.1",
     "react-dom": "18.3.1"
   },
   "devDependencies": {
+    "@types/qrcode": "1.5.5",
     "@eventusgo/vite-plugin": "__EVENTUS_VITE_PLUGIN_VERSION__",
     "@types/react": "18.3.28",
     "@types/react-dom": "18.3.7",

package/template/src/App.tsx

@@ -1,21 +1,31 @@
 import { useEffect, useState } from "react";
 import manifest from "virtual:eventus-manifest";
+import QRCode from "qrcode";
 import {
   eventus,
   type EventusContext,
   type EventusRuntimeSource,
 } from "@eventusgo/sdk";
+import {
+  fetchDevPreviewDescriptor,
+  isBridgeUnavailableError,
+  type EventusDevPreviewDescriptor,
+} from "./dev-preview";
 
 type LoadState =
   | { status: "idle" | "loading" }
   | { status: "ready"; context: EventusContext }
+  | {
+      status: "bridge-unavailable";
+      preview: EventusDevPreviewDescriptor | null;
+    }
   | { status: "error"; message: string };
 
 export default function App() {
   const [state, setState] = useState<LoadState>({ status: "loading" });
-  const [runtimeSource, setRuntimeSource] = useState<EventusRuntimeSource | "loading">(
-    "loading",
-  );
+  const [runtimeSource, setRuntimeSource] = useState<
+    EventusRuntimeSource | "bridge-unavailable" | "loading"
+  >("loading");
 
   useEffect(() => {
     let cancelled = false;
@@ -41,10 +51,26 @@ export default function App() {
         const context = await eventus.getContext();
 
         if (!cancelled && !receivedReadyEvent) {
-          setRuntimeSource("mock");
+          setRuntimeSource(window.Eventus ? "native" : "mock");
           setState({ status: "ready", context });
         }
       } catch (error) {
+        if (receivedReadyEvent || cancelled) {
+          return;
+        }
+
+        if (isBridgeUnavailableError(error)) {
+          const preview = await fetchDevPreviewDescriptor();
+          if (!cancelled && !receivedReadyEvent) {
+            setRuntimeSource("bridge-unavailable");
+            setState({
+              status: "bridge-unavailable",
+              preview,
+            });
+          }
+          return;
+        }
+
         if (!cancelled) {
           setState({
             status: "error",
@@ -68,7 +94,9 @@ export default function App() {
     runtimeSource === "native"
       ? "Native bridge detected"
       : runtimeSource === "mock"
-        ? "Browser mock mode active"
+        ? "Explicit mock mode active"
+        : runtimeSource === "bridge-unavailable"
+          ? "Open this mini app inside Eventus X"
         : "Detecting runtime…";
 
   return (
@@ -90,6 +118,10 @@ export default function App() {
           <p className="error-text">{state.message}</p>
         ) : null}
 
+        {state.status === "bridge-unavailable" ? (
+          <DeveloperHandoff preview={state.preview} />
+        ) : null}
+
         {state.status === "ready" ? (
           <dl className="details-grid">
             <div>
@@ -120,3 +152,102 @@ export default function App() {
     </main>
   );
 }
+
+function DeveloperHandoff({
+  preview,
+}: {
+  preview: EventusDevPreviewDescriptor | null;
+}) {
+  if (!preview) {
+    return (
+      <div className="handoff-panel">
+        <h2>Open inside Eventus X</h2>
+        <p>
+          This mini app needs the Eventus bridge to access the real runtime.
+          Open it from Eventus X to test it with production-like behavior.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="handoff-panel">
+      <div className="handoff-copy">
+        <h2>Live preview from your phone</h2>
+        <p>
+          Open Eventus X, go to <strong>Developer</strong>, and scan this QR
+          code to launch the mini app with the real Eventus bridge.
+        </p>
+        <dl className="preview-grid">
+          <div>
+            <dt>Preview URL</dt>
+            <dd>
+              <code>{preview.urls.preview}</code>
+            </dd>
+          </div>
+          <div>
+            <dt>Local URL</dt>
+            <dd>
+              <code>{preview.urls.local}</code>
+            </dd>
+          </div>
+          {preview.urls.network ? (
+            <div>
+              <dt>Network URL</dt>
+              <dd>
+                <code>{preview.urls.network}</code>
+              </dd>
+            </div>
+          ) : null}
+          <div>
+            <dt>Permissions</dt>
+            <dd>{preview.manifest.permissions?.join(", ") ?? "None"}</dd>
+          </div>
+        </dl>
+        <p className="hint-text">
+          Your phone and computer must be on the same local network.
+        </p>
+      </div>
+      <QrPanel payload={preview} />
+    </div>
+  );
+}
+
+function QrPanel({
+  payload,
+}: {
+  payload: EventusDevPreviewDescriptor;
+}) {
+  const [svg, setSvg] = useState("");
+
+  useEffect(() => {
+    let cancelled = false;
+
+    void (async () => {
+      const nextSvg = await QRCode.toString(JSON.stringify(payload), {
+        type: "svg",
+        width: 220,
+        margin: 1,
+      });
+      if (!cancelled) {
+        setSvg(nextSvg);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [payload]);
+
+  return (
+    <div className="qr-panel">
+      <div
+        className="qr-code"
+        aria-label="Eventus live preview QR code"
+        dangerouslySetInnerHTML={{
+          __html: svg || "<div class='qr-placeholder'>Generating QR…</div>",
+        }}
+      />
+    </div>
+  );
+}

package/template/src/dev-preview.ts

@@ -0,0 +1,102 @@
+export type EventusDevPreviewDescriptor = {
+  type: "eventus-dev-preview";
+  version: 1;
+  manifest: {
+    name: string;
+    appId: string;
+    version: string;
+    permissions?: string[];
+  };
+  urls: {
+    local: string;
+    network: string | null;
+    preview: string;
+  };
+};
+
+export function isBridgeUnavailableError(error: unknown): boolean {
+  return (
+    error instanceof Error && error.name === "EventusBridgeUnavailableError"
+  );
+}
+
+export async function fetchDevPreviewDescriptor(): Promise<EventusDevPreviewDescriptor | null> {
+  if (typeof fetch !== "function") {
+    return null;
+  }
+
+  try {
+    const response = await fetch("/__eventus__/preview.json", {
+      headers: {
+        Accept: "application/json",
+      },
+    });
+    if (!response.ok) {
+      return null;
+    }
+
+    const json = (await response.json()) as unknown;
+    return parseDevPreviewDescriptor(json);
+  } catch {
+    return null;
+  }
+}
+
+export function parseDevPreviewDescriptor(
+  value: unknown,
+): EventusDevPreviewDescriptor | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  const descriptor = value as Record<string, unknown>;
+  const manifest = descriptor.manifest;
+  const urls = descriptor.urls;
+
+  if (
+    descriptor.type !== "eventus-dev-preview" ||
+    descriptor.version !== 1 ||
+    !manifest ||
+    typeof manifest !== "object" ||
+    Array.isArray(manifest) ||
+    !urls ||
+    typeof urls !== "object" ||
+    Array.isArray(urls)
+  ) {
+    return null;
+  }
+
+  const nextManifest = manifest as Record<string, unknown>;
+  const nextUrls = urls as Record<string, unknown>;
+  const permissions = nextManifest.permissions;
+
+  if (
+    typeof nextManifest.name !== "string" ||
+    typeof nextManifest.appId !== "string" ||
+    typeof nextManifest.version !== "string" ||
+    typeof nextUrls.local !== "string" ||
+    (nextUrls.network !== null && typeof nextUrls.network !== "string") ||
+    typeof nextUrls.preview !== "string" ||
+    (permissions !== undefined &&
+      (!Array.isArray(permissions) ||
+        permissions.some((permission) => typeof permission !== "string")))
+  ) {
+    return null;
+  }
+
+  return {
+    type: "eventus-dev-preview",
+    version: 1,
+    manifest: {
+      name: nextManifest.name,
+      appId: nextManifest.appId,
+      version: nextManifest.version,
+      ...(permissions ? { permissions: permissions as string[] } : {}),
+    },
+    urls: {
+      local: nextUrls.local,
+      network: nextUrls.network as string | null,
+      preview: nextUrls.preview,
+    },
+  };
+}

package/template/src/styles.css

@@ -67,6 +67,76 @@ h1 {
   font-weight: 600;
 }
 
+.handoff-panel {
+  margin: 24px 0;
+  display: grid;
+  gap: 20px;
+}
+
+.handoff-copy h2 {
+  margin: 0 0 8px;
+  font-size: 1.5rem;
+}
+
+.handoff-copy p {
+  margin: 0;
+  color: #465d82;
+}
+
+.preview-grid {
+  margin: 20px 0 0;
+  display: grid;
+  gap: 12px;
+}
+
+.preview-grid div {
+  padding: 14px 16px;
+  border-radius: 16px;
+  background: #f8fbff;
+  border: 1px solid rgba(16, 35, 71, 0.08);
+}
+
+.preview-grid code {
+  word-break: break-all;
+}
+
+.hint-text {
+  margin-top: 16px;
+  font-size: 0.95rem;
+}
+
+.qr-panel {
+  display: grid;
+  place-items: center;
+  padding: 20px;
+  border-radius: 24px;
+  background: linear-gradient(180deg, #fefefe 0%, #f3f7ff 100%);
+  border: 1px solid rgba(16, 35, 71, 0.08);
+}
+
+.qr-code {
+  width: min(260px, 100%);
+  aspect-ratio: 1;
+  display: grid;
+  place-items: center;
+}
+
+.qr-code svg {
+  width: 100%;
+  height: auto;
+}
+
+.qr-placeholder {
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 100%;
+  border-radius: 20px;
+  background: #eef6ff;
+  color: #22548d;
+  font-weight: 600;
+}
+
 .details-grid {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
@@ -111,4 +181,15 @@ dd {
   .card {
     padding: 24px;
   }
+
+  .handoff-panel {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (min-width: 641px) {
+  .handoff-panel {
+    grid-template-columns: minmax(0, 1.3fr) minmax(220px, 0.7fr);
+    align-items: start;
+  }
 }