@glassly/create-miniapp 0.1.0-dev.1

package/README.md

@@ -0,0 +1,34 @@
+# @glassly/create-miniapp
+
+Scaffold a new [Glassly](https://github.com/tetramo-labs/glassly)
+miniapp project — the `bun create` starter for apps that run on Glassly
+smart glasses.
+
+## Usage
+
+```sh
+bunx @glassly/create-miniapp my-app
+cd my-app
+bun install
+bun run dev
+```
+
+> **Bun-only.** The scaffolder and the generated project's tooling run under
+> [Bun](https://bun.sh) — use `bun` / `bunx`, not `npx`.
+
+The generated project comes wired with
+[`@glassly/miniapp`](https://www.npmjs.com/package/@glassly/miniapp) (the SDK
+runtime) and [`@glassly/miniapp-cli`](https://www.npmjs.com/package/@glassly/miniapp-cli)
+(the `dev` / `build` / `pack` author flow), a `miniapp.json` manifest, and a
+TypeScript setup. Dependency pins are stamped at publish time to the exact
+SDK versions this scaffolder shipped with, so a generated project installs
+on any release channel.
+
+To publish a finished miniapp to the Glassly Miniapp Store, see
+[`@glassly/cli`](https://www.npmjs.com/package/@glassly/cli) (`glassly login` /
+`glassly publish`).
+
+## Part of Glassly
+
+Source lives in the [Glassly monorepo](https://github.com/tetramo-labs/glassly)
+under `sdk/create-miniapp`. Issues and contributions welcome there.

package/bin/create-miniapp

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+// Extensionless launcher: npm strips bin entries that point at .ts files.
+import "./index.ts"

package/bin/index.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env bun
+
+import * as fs from "fs"
+import * as path from "path"
+import {intro, outro, text, select, isCancel, cancel, note} from "@clack/prompts"
+
+type GlassesType = "display" | "camera"
+
+interface CliFlags {
+  projectName?: string
+  type?: GlassesType
+}
+
+function parseArgs(argv: string[]): CliFlags {
+  const flags: CliFlags = {}
+  for (const arg of argv) {
+    if (arg.startsWith("--type=")) {
+      const value = arg.slice("--type=".length)
+      if (value === "display" || value === "camera") {
+        flags.type = value
+      } else {
+        console.error(`Invalid --type value: "${value}". Expected "display" or "camera".`)
+        process.exit(1)
+      }
+    } else if (!arg.startsWith("-") && !flags.projectName) {
+      flags.projectName = arg
+    }
+  }
+  return flags
+}
+
+function toKebabCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/[\s_]+/g, "-")
+    .toLowerCase()
+}
+
+function validateProjectName(name: string): string | undefined {
+  if (!name.trim()) return "Project name is required"
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9-_ ]*$/.test(name)) {
+    return "Use letters, numbers, dashes, underscores, or spaces (cannot start with a symbol)"
+  }
+  if (fs.existsSync(path.resolve(process.cwd(), name))) {
+    return `Directory "${name}" already exists`
+  }
+  return undefined
+}
+
+function bailIfCancelled<T>(value: T | symbol): T {
+  if (isCancel(value)) {
+    cancel("Cancelled.")
+    process.exit(0)
+  }
+  return value as T
+}
+
+const flags = parseArgs(process.argv.slice(2))
+
+intro("create-miniapp")
+
+let projectName = flags.projectName
+if (projectName) {
+  const err = validateProjectName(projectName)
+  if (err) {
+    cancel(err)
+    process.exit(1)
+  }
+} else {
+  projectName = bailIfCancelled(
+    await text({
+      message: "What's your project name?",
+      placeholder: "my-miniapp",
+      validate: validateProjectName,
+    }),
+  )
+}
+
+let glassesType = flags.type
+if (!glassesType) {
+  glassesType = bailIfCancelled(
+    await select<GlassesType>({
+      message: "What kind of glasses is this miniapp for?",
+      options: [
+        {
+          value: "display",
+          label: "Display glasses",
+          hint: "Even Realities G1/G2, Vuzix Z100",
+        },
+        {
+          value: "camera",
+          label: "Camera glasses",
+          hint: "Mentra Live",
+        },
+      ],
+    }),
+  )
+}
+
+const targetDir = path.resolve(process.cwd(), projectName)
+const templateDir = path.resolve(import.meta.dirname, "..", "template")
+
+const kebabName = toKebabCase(projectName)
+const packageName = `com.glassly.${kebabName}`
+const hardwareRequirements =
+  glassesType === "camera"
+    ? [
+        {type: "CAMERA", level: "REQUIRED"},
+        {type: "MICROPHONE", level: "REQUIRED"},
+      ]
+    : [
+        {type: "DISPLAY", level: "REQUIRED"},
+        {type: "MICROPHONE", level: "REQUIRED"},
+      ]
+
+function renderFile(srcPath: string, destPath: string): void {
+  if (path.basename(srcPath) === "miniapp.json") {
+    const raw = fs.readFileSync(srcPath, "utf-8")
+    const manifest = JSON.parse(raw.replace(/\{\{packageName\}\}/g, packageName))
+    manifest.hardwareRequirements = hardwareRequirements
+    fs.writeFileSync(destPath, JSON.stringify(manifest, null, 2) + "\n")
+    return
+  }
+
+  const content = fs.readFileSync(srcPath, "utf-8").replace(/\{\{packageName\}\}/g, packageName)
+  fs.writeFileSync(destPath, content)
+}
+
+function copyDir(src: string, dest: string): void {
+  fs.mkdirSync(dest, {recursive: true})
+  for (const entry of fs.readdirSync(src, {withFileTypes: true})) {
+    const srcPath = path.join(src, entry.name)
+    // npm strips literal `.gitignore` files on publish; the template
+    // ships it as `_gitignore` instead and we rename on copy so the
+    // scaffolded project starts with a proper `.gitignore`.
+    const renamed = entry.name === "_gitignore" ? ".gitignore" : entry.name
+    const destPath = path.join(dest, renamed)
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath)
+    } else {
+      renderFile(srcPath, destPath)
+    }
+  }
+}
+
+copyDir(templateDir, targetDir)
+
+note(`cd ${projectName}\nbun install\nbun dev`, "Next steps")
+
+outro(`Created miniapp in ./${projectName}`)

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@glassly/create-miniapp",
+  "version": "0.1.0-dev.1",
+  "description": "Scaffold a new Glassly miniapp project",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "tag": "dev"
+  },
+  "bin": {
+    "create-miniapp": "bin/create-miniapp"
+  },
+  "scripts": {
+    "build": "echo 'No build needed \u2014 runs via bun'"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "keywords": [
+    "glassly",
+    "glassly",
+    "miniapp",
+    "create",
+    "scaffold"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tetramo-labs/glassly.git",
+    "directory": "sdk/create-miniapp"
+  },
+  "homepage": "https://github.com/tetramo-labs/glassly/tree/dev/sdk/create-miniapp#readme",
+  "bugs": {
+    "url": "https://github.com/tetramo-labs/glassly/issues"
+  }
+}

package/template/AGENTS.md

@@ -0,0 +1,18 @@
+# Miniapp implementation rules
+
+- Put glasses subscriptions, `session.*` calls, durable state, and logic that
+  must survive UI closure in `src/background/`.
+- Put React, rendering, DOM access, and browser UI libraries in `src/ui/`.
+- The layers do not share memory. Exchange serializable data through the typed
+  `glassly.*` / `session.ui.*` channels declared in `src/shared/channels.ts`.
+- The background is a bare JavaScript engine, not a browser or Node. Supported
+  globals are `console`, timers, `queueMicrotask`, `fetch`, `WebSocket`,
+  `localStorage`, `crypto.getRandomValues`, `crypto.randomUUID`, `TextEncoder`,
+  `TextDecoder`, `atob`, `btoa`, and the SDK-supported `AbortController` subset.
+- Do not use `window`, `document`, DOM elements, `performance`,
+  `XMLHttpRequest`, `crypto.subtle`, Node built-ins, `process`, or runtime module
+  resolution in `src/background/`. Use `Date.now()` instead of
+  `performance.now()`.
+- `bun run dev` is live and temporary. Multiple dev miniapps can coexist when
+  they use distinct manifest package names. Use `bun run release` for a
+  persistent local install that runs without the development computer.

package/template/README.md

@@ -0,0 +1,37 @@
+# Glassly miniapp
+
+This project has two runtimes with different jobs:
+
+- `src/background/` is always on while the miniapp is enabled. Put glasses
+  subscriptions, `session.*` calls, durable state, and logic that must keep
+  running after the UI closes here.
+- `src/ui/` is a normal WebView that exists only while the user has the miniapp
+  open. Put React, rendering, DOM access, and browser UI libraries here.
+
+The background is a bare JavaScript engine, not a browser or Node. It supports
+`console`, timers, `fetch`, `WebSocket`, `localStorage`,
+`crypto.getRandomValues`, `crypto.randomUUID`, `TextEncoder`, `TextDecoder`,
+`atob`, `btoa`, and the SDK-supported `AbortController` subset. It does not
+support `window`, `document`, DOM elements, `performance`, `XMLHttpRequest`,
+`crypto.subtle`, Node built-ins, `process`, or runtime module resolution. Use
+`Date.now()` instead of `performance.now()`.
+
+`bun run build` checks background source (including imported shared files) and
+reports common unsupported browser or Node APIs with a file, line, and supported
+alternative before it emits a bundle.
+
+The layers do not share memory. Exchange serializable data through the typed
+`glassly.*` / `session.ui.*` message bus declared in `src/shared/channels.ts`.
+
+## Commands
+
+```bash
+bun run dev      # live, temporary; keep the computer and CLI running
+bun run release  # persistent local install that runs without the computer
+bun run build    # build both layers into dist/
+```
+
+The Glassly App keeps one dev entry per manifest package name, so you can scan and
+test multiple dev miniapps side by side. It also caches each entry's name and
+icon. Rescanning the same package updates that entry. Use `bun run release` when
+you want the miniapp to run without the computer.

package/template/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+build/
+*.zip
+.env
+.env.local
+.DS_Store

package/template/build.ts

@@ -0,0 +1,81 @@
+/**
+ * Production build script — two-output bundle.
+ *
+ * Two-layer miniapps ship TWO bundles in one zip:
+ *   - dist/background/index.js     — JSContext entry, no DOM
+ *   - dist/ui/index.html + assets  — WebView entry, full DOM
+ *
+ * Bun.build() handles both. The background bundle uses `format: "iife"`
+ * because JSC + Zipline/QuickJS evaluate it as a classic script — any
+ * top-level ESM `export` is a SyntaxError there. `@glassly/miniapp/background`
+ * is bundled in (not external) because the JSContext has no module
+ * resolver; the host's polyfill installs `__dispatch`/`__deliver` but
+ * does NOT provide the SDK surface. The UI bundle uses target: "browser"
+ * with no externals.
+ *
+ * Build-time env vars: any `PUBLIC_*` key in your shell or
+ * miniapp-local `.env` gets inlined into both bundles via define.
+ * Anything inlined into the UI bundle is visible in WebView network
+ * requests and source maps — secrets MUST live behind your own backend
+ * rather than in PUBLIC_*.
+ *
+ * Add bundler plugins (Tailwind, Vue, etc.) by pushing them into the
+ * matching `plugins` array. For example, with Tailwind v4 (UI side only):
+ *
+ *     const tailwind = (await import("bun-plugin-tailwind")).default
+ *     uiBuild.plugins.push(tailwind)
+ *
+ * Output goes to ./dist with the shape `glassly-miniapp release` expects.
+ */
+
+import {rm} from "fs/promises"
+import {backgroundRuntimeGuardPlugin, reactSingletonPlugin} from "@glassly/miniapp-cli/build-helpers"
+
+const distDir = "./dist"
+
+// Wipe dist/ so old chunks don't accumulate across builds.
+await rm(distDir, {recursive: true, force: true})
+
+// Pick up PUBLIC_* env vars from the shell / .env. Bun loads .env
+// from cwd automatically; we just need to forward the keys to define.
+const define: Record<string, string> = {}
+for (const [k, v] of Object.entries(process.env)) {
+  if (k.startsWith("PUBLIC_") && typeof v === "string") {
+    define[`process.env.${k}`] = JSON.stringify(v)
+  }
+}
+
+const backgroundResult = await Bun.build({
+  entrypoints: ["./src/background/index.ts"],
+  outdir: `${distDir}/background`,
+  target: "browser",
+  format: "iife",
+  plugins: [backgroundRuntimeGuardPlugin(import.meta.url)],
+  minify: false,
+  define,
+})
+
+if (!backgroundResult.success) {
+  console.error("Background build failed:")
+  for (const log of backgroundResult.logs) console.error(log)
+  process.exit(1)
+}
+
+const uiResult = await Bun.build({
+  entrypoints: ["./src/ui/index.html"],
+  outdir: `${distDir}/ui`,
+  target: "browser",
+  plugins: [reactSingletonPlugin(import.meta.url)],
+  minify: true,
+  define,
+})
+
+if (!uiResult.success) {
+  console.error("UI build failed:")
+  for (const log of uiResult.logs) console.error(log)
+  process.exit(1)
+}
+
+// Silence on success — the dev-server's `reload →` line is the
+// developer-facing confirmation. Failures already print via the
+// .success branches above.

package/template/miniapp.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "./node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json",
+  "packageName": "{{packageName}}",
+  "version": "1.0.0",
+  "name": "My Miniapp",
+  "description": "A Glassly miniapp",
+  "icon": "icon.png",
+  "type": "standard",
+  "sdkVersion": "0.3.0",
+  "minHostVersion": "1.42.0",
+  "entry": {
+    "background": "background/index.js",
+    "ui": "ui/index.html"
+  },
+  "permissions": [],
+  "hardwareRequirements": [
+    {"type": "DISPLAY", "level": "REQUIRED", "description": "Renders text + UI on glasses"}
+  ]
+}

package/template/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "scripts": {
+    "dev": "glassly-miniapp dev",
+    "build": "bun run build.ts",
+    "typecheck": "tsc --noEmit",
+    "release": "glassly-miniapp release",
+    "pack": "glassly-miniapp pack"
+  },
+  "dependencies": {
+    "@glassly/miniapp": "0.1.0-dev.62",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@glassly/miniapp-cli": "0.1.0-dev.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/template/src/background/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Background JSContext entry point. The Glassly host loads this file
+ * inside a per-miniapp JSContext (iOS-JSC / Android-QuickJS) and calls
+ * the `registerMiniapp` handler once CONNECT completes. All glasses-side
+ * logic lives in here.
+ *
+ * Background runs **always** while the host app process is alive — even
+ * when the user hasn't opened the miniapp's UI. Register your event
+ * subscriptions inside the handler; the runtime tears them down when the
+ * miniapp is disabled or uninstalled.
+ */
+
+import {registerMiniapp} from "@glassly/miniapp/background"
+import type {Channels} from "../shared/channels"
+
+registerMiniapp<Channels>(async (session) => {
+  // Hydrate any persisted state from session.storage (string KV — JSON-encode
+  // structured data yourself).
+  // const stored = await session.storage.get("notes")
+  // const notes: Note[] = stored ? JSON.parse(stored) : []
+
+  // Glasses button → demo display. display.render() replaces the whole frame:
+  // describe everything that should be on screen and the host diffs it against
+  // the previous frame (stable ids update in place; render([]) clears). Box
+  // coordinates are raw device px — read `session.capabilities.display`
+  // (populated on the "ready" event) for the real canvas size.
+  session.input.onButtonPress(() => {
+    const d = session.capabilities?.display
+    void session.display.render([
+      {
+        type: "text",
+        id: "hello",
+        box: {x: 0, y: 0, w: d?.width ?? 576, h: d?.height ?? 288},
+        text: "Hello from GlasslyJS",
+      },
+    ])
+  })
+
+  // UI bus: forward "ping" → "pong" with a roundtrip timestamp.
+  session.ui.onOpen(() => {
+    // Push initial state to the WebView whenever it opens.
+    session.ui.send("pong", {at: Date.now(), roundtripMs: 0})
+  })
+  session.ui.on("ping", ({at}) => {
+    const roundtripMs = Date.now() - at
+    session.ui.send("pong", {at: Date.now(), roundtripMs})
+  })
+})

package/template/src/shared/channels.ts

@@ -0,0 +1,26 @@
+/**
+ * Typed channel registry — single source of truth for the names + payload
+ * shapes that flow between this miniapp's background JSContext and its UI
+ * WebView. Both halves import this file at build time; the bundler inlines
+ * the declarations so there's no runtime resolution.
+ *
+ * Add a key per channel. The TypeScript generic on `glassly.send` /
+ * `glassly.on` / `session.ui.send` / `session.ui.on` enforces names + payload
+ * shapes at compile time so the two halves can't drift.
+ */
+
+export interface Channels {
+  // WebView → background
+  "ping": {at: number}
+
+  // background → WebView
+  "pong": {at: number; roundtripMs: number}
+}
+
+declare global {
+  // Augment the `glassly` global from @glassly/miniapp/ui with this miniapp's
+  // typed channel registry so authors get compile-time enforcement on every
+  // glassly.send / glassly.on call without re-declaring it.
+  // eslint-disable-next-line no-var
+  var glassly: import("@glassly/miniapp/ui").TypedUiGlobal<Channels>
+}

package/template/src/ui/App.tsx

@@ -0,0 +1,26 @@
+import {useEffect, useState} from "react"
+
+export function App() {
+  const [roundtripMs, setRoundtripMs] = useState<number | null>(null)
+
+  useEffect(() => {
+    const unsub = glassly.on("pong", ({roundtripMs}) => {
+      setRoundtripMs(roundtripMs)
+    })
+    return unsub
+  }, [])
+
+  const ping = () => {
+    glassly.send("ping", {at: Date.now()})
+  }
+
+  return (
+    <div className="app">
+      <h1>{`{{packageName}}`}</h1>
+      <p>Round-trip to background: {roundtripMs == null ? "—" : `${roundtripMs} ms`}</p>
+      <button type="button" onClick={ping}>
+        Ping background
+      </button>
+    </div>
+  )
+}

package/template/src/ui/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no" />
+    <title>{{packageName}}</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/template/src/ui/main.tsx

@@ -0,0 +1,30 @@
+/**
+ * WebView entry point. Imports the `glassly` global from the auto-injected
+ * host shim and the typed `Channels` registry from src/shared/. The
+ * WebView has zero direct native access — all hardware calls (glasses
+ * display, sensors, BLE, etc.) go through `glassly.send(channel, payload)`
+ * to background, which translates them into `session.*` SDK calls.
+ */
+
+import {createRoot} from "react-dom/client"
+import {MiniappProvider} from "@glassly/miniapp/ui"
+import "../shared/channels"
+import {App} from "./App"
+import "./styles.css"
+
+const root = document.getElementById("root")
+if (!root) {
+  throw new Error("Missing #root element in index.html")
+}
+
+// MiniappProvider syncs <html class="dark"> with the host color scheme.
+// Purely a CSS theme bridge — does NOT construct a MiniappSession.
+createRoot(root).render(
+  <MiniappProvider>
+    <App />
+  </MiniappProvider>,
+)
+
+// MUST call glassly.ready() on bootstrap so the host knows the WebView is
+// mounted and can flush any buffered `session.ui.send` calls.
+glassly.ready()

package/template/src/ui/styles.css

@@ -0,0 +1,43 @@
+:root {
+  color-scheme: light dark;
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+
+body {
+  margin: 0;
+  background: #0b0b0b;
+  color: #f5f5f5;
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.app {
+  text-align: center;
+  padding: 24px;
+}
+
+h1 {
+  font-size: 1.5rem;
+  margin: 0 0 12px;
+}
+
+p {
+  margin: 8px 0 24px;
+  opacity: 0.7;
+}
+
+button {
+  font-size: 1rem;
+  padding: 12px 24px;
+  border-radius: 12px;
+  border: none;
+  background: #4a9eff;
+  color: white;
+  cursor: pointer;
+}
+
+button:active {
+  transform: scale(0.97);
+}

package/template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}