@odyn-app/api 0.1.0 → 0.2.0

package/README.md

@@ -2,10 +2,18 @@
 
 The building kit for [Odyn](https://github.com/New-Genre/odyn-extensions) extensions.
 
+Start a new extension, work on it, and publish it:
+
 ```bash
-bun add @odyn-app/api
+bunx --package @odyn-app/api odyn-extension create "My extension"
+cd my-extension
+bun install
+bun run dev       # rebuilds on every save; Odyn reloads it
+bun run publish   # sends it to Odyn's Marketplace for review
 ```
 
+Your extension's entry file:
+
 ```ts
 import { defineExtension } from '@odyn-app/api'
 
@@ -16,10 +24,13 @@ defineExtension({
 })
 ```
 
+- `odyn-extension`: the command-line tool above — `create`, `dev`, `build`, `check`, `pull <id>` and `publish`.
 - `@odyn-app/api`: `defineExtension`, the `odyn` bridge, the manifest types and the manifest checker.
 - `@odyn-app/api/ui`: Odyn's `Button`, `Skeleton`, `SettingRow`, `Orb` and `cn`, for extension pages.
 - `@odyn-app/api/theme.css`: Odyn's colours, fonts and light/dark themes. Add `@import "@odyn-app/api/theme.css";` to a page's stylesheet.
 
-Every extension runs sandboxed, and each call is checked against the permissions the user granted. To make one and publish it to Odyn's Marketplace, see the [contribution guide](https://github.com/New-Genre/odyn-extensions/blob/main/CONTRIBUTING.md).
+Every extension runs sandboxed, and each call is checked against the permissions the user granted.
+
+**[Read the docs](https://www.odyn.build/docs/extensions)** for what extensions can and can't do, every permission and limit, and the full reference. To publish one to Odyn's Marketplace, see the [contribution guide](https://github.com/New-Genre/odyn-extensions/blob/main/CONTRIBUTING.md).
 
 MIT licence.

package/cli/build.mjs

@@ -0,0 +1,146 @@
+/**
+ * Builds one extension folder. Shared by `odyn-extension build` (an author's
+ * own folder, built in place into `dist/`) and the public repo's release
+ * build (built into a separate folder that becomes the download).
+ *
+ * What gets built, when the extension has it:
+ *   - commands, `src/index.ts`  → `dist/index.js` (one self-contained script)
+ *   - a page, `index.html`      → `dist/panel/`
+ *   - a background helper, `src/helper.ts` → `dist/helper.js`
+ * Every manifest is checked with the same checker Odyn runs on a download,
+ * so a broken one fails here rather than on someone's Mac.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/postcss'
+import { build } from 'vite'
+import { validateManifest } from '../dist/index.js'
+
+const PANEL_DIR = join('dist', 'panel')
+const HELPER_SOURCE = join('src', 'helper.ts')
+const COMMANDS_SOURCE = join('src', 'index.ts')
+/** The Chinese hand-drawn font is 12 MB on its own; Chinese text falls back to a system font. */
+const SKIPPED_FONT_FAMILIES = new Set(['Xiaolai'])
+/** The drawing library's folder, as it appears in the paths of the files a build uses. */
+const DRAWING_LIBRARY_PATH = '/node_modules/@excalidraw/excalidraw/'
+/** The only parts of an extension's `package.json` Odyn reads. */
+const SHIPPED_PACKAGE_KEYS = ['name', 'version', 'private', 'odyn']
+
+/** Reads an extension's `package.json`. */
+export function readPackage(sourceDir) {
+  return JSON.parse(readFileSync(join(sourceDir, 'package.json'), 'utf8'))
+}
+
+/**
+ * Checks an extension folder's manifest. Returns the problems found.
+ * `official` relaxes the rules for extensions made by Odyn.
+ */
+export function checkExtension(sourceDir, { official = false } = {}) {
+  if (!existsSync(join(sourceDir, 'package.json'))) return ['This folder has no package.json.']
+  const pkg = readPackage(sourceDir)
+  if (typeof pkg.odyn !== 'object' || pkg.odyn === null) return ['package.json has no "odyn" section.']
+  const problems = []
+  if (pkg.private !== true) problems.push('"private": true is required, so it is never published to npm by mistake.')
+  const manifest = { ...pkg.odyn, version: pkg.version }
+  problems.push(...validateManifest(manifest, { official }))
+  return problems
+}
+
+/**
+ * Stops the build if a page or helper reaches outside its own folder — an
+ * extension must never quietly bundle another's files. Installed packages
+ * (the kit, React and so on) are fine.
+ */
+function stayInsideFolder(sourceDir, onDrawingLibrary) {
+  return {
+    name: 'odyn-stay-inside-folder',
+    generateBundle() {
+      for (const moduleId of this.getModuleIds()) {
+        const library = moduleId.indexOf(DRAWING_LIBRARY_PATH)
+        if (library !== -1) onDrawingLibrary(moduleId.slice(0, library + DRAWING_LIBRARY_PATH.length))
+        const file = moduleId.split('?')[0]
+        if (!file.startsWith('/') || file.includes('/node_modules/') || !existsSync(file)) continue
+        if (!file.startsWith(`${sourceDir}/`)) {
+          this.error(`${relative(sourceDir, file)} is outside this extension's folder. Extensions may only use their own files and installed packages.`)
+        }
+      }
+    },
+  }
+}
+
+/** Copies the drawing library's fonts in, when the page uses the library. */
+function copyFonts(libraryRoot, panelDir) {
+  const fontsRoot = join(libraryRoot, 'dist', 'prod', 'fonts')
+  if (!existsSync(fontsRoot)) throw new Error(`Drawing fonts not found at ${fontsRoot}`)
+  for (const family of readdirSync(fontsRoot)) {
+    if (SKIPPED_FONT_FAMILIES.has(family)) continue
+    cpSync(join(fontsRoot, family), join(panelDir, 'fonts', family), { recursive: true })
+  }
+}
+
+/**
+ * Builds the extension in `sourceDir`. With no `outputDir` it builds in place
+ * (into `sourceDir/dist`), ready for "Install from folder". With one, it
+ * writes a complete download there: the built files, the agent guide and a
+ * trimmed `package.json`.
+ */
+export async function buildExtension(sourceDir, { outputDir = null, official = false } = {}) {
+  const root = resolve(sourceDir)
+  const problems = checkExtension(root, { official })
+  if (problems.length > 0) throw new Error(problems.join(' '))
+  const pkg = readPackage(root)
+  const inPlace = outputDir === null || resolve(outputDir) === root
+  const target = inPlace ? root : resolve(outputDir)
+  rmSync(inPlace ? join(root, 'dist') : target, { recursive: true, force: true })
+  mkdirSync(join(target, 'dist'), { recursive: true })
+
+  if (existsSync(join(root, 'index.html'))) {
+    const panelDir = join(target, PANEL_DIR)
+    /** Where the drawing library is installed, once the page is seen to use it. */
+    let drawingLibraryRoot = null
+    await build({
+      configFile: false,
+      root,
+      base: './',
+      logLevel: 'warn',
+      plugins: [react(), stayInsideFolder(root, (libraryRoot) => { drawingLibraryRoot = libraryRoot })],
+      // Tailwind reads the extension's own folder (and the kit, which its theme points at).
+      css: { postcss: { plugins: [tailwindcss({ base: root })] } },
+      build: { outDir: panelDir, emptyOutDir: true, sourcemap: false, chunkSizeWarningLimit: 4096 },
+    })
+    if (drawingLibraryRoot !== null) copyFonts(drawingLibraryRoot, panelDir)
+  }
+
+  // Commands and the background helper each run in a page with no module
+  // loader, so everything is bundled into a single plain script.
+  const scripts = [
+    { source: COMMANDS_SOURCE, name: 'OdynExtension', fileName: 'index.js' },
+    { source: HELPER_SOURCE, name: 'OdynHelper', fileName: 'helper.js' },
+  ]
+  for (const script of scripts.filter(({ source }) => existsSync(join(root, source)))) {
+    await build({
+      configFile: false,
+      root,
+      logLevel: 'warn',
+      plugins: [stayInsideFolder(root, () => undefined)],
+      build: {
+        outDir: join(target, 'dist'),
+        emptyOutDir: false,
+        sourcemap: false,
+        minify: false,
+        lib: { entry: join(root, script.source), formats: ['iife'], name: script.name, fileName: () => script.fileName },
+      },
+    })
+  }
+
+  if (!inPlace) {
+    const skillFolder = pkg.odyn?.agent?.skillFolder
+    if (typeof skillFolder === 'string' && existsSync(join(root, skillFolder))) {
+      cpSync(join(root, skillFolder), join(target, skillFolder), { recursive: true })
+    }
+    const shipped = Object.fromEntries(SHIPPED_PACKAGE_KEYS.filter((key) => key in pkg).map((key) => [key, pkg[key]]))
+    writeFileSync(join(target, 'package.json'), `${JSON.stringify(shipped, null, 2)}\n`)
+  }
+  return { id: pkg.odyn.id, version: pkg.version }
+}

package/cli/github.mjs

@@ -0,0 +1,190 @@
+/**
+ * Talking to GitHub for `odyn-extension publish` and `pull`.
+ *
+ * Publishing never clones the public repo. It copies the repo into the
+ * author's own GitHub account (a fork), writes the extension's files there
+ * as one commit and opens a pull request — all through GitHub's web API.
+ */
+import { execFileSync, spawn } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export const UPSTREAM_OWNER = 'New-Genre'
+export const UPSTREAM_REPO = 'odyn-extensions'
+export const UPSTREAM_BRANCH = 'main'
+const API = 'https://api.github.com'
+/**
+ * Odyn's GitHub sign-in app (New-Genre's "Odyn extensions" OAuth app, with
+ * device sign-in switched on). Device sign-in — a short code you type on
+ * github.com — needs no secret, so the id is safe to ship. Empty until the
+ * app exists; until then `gh auth login` or `GITHUB_TOKEN` is used.
+ */
+const ODYN_GITHUB_CLIENT_ID = ''
+const GITHUB_CLIENT_ID = process.env.ODYN_GITHUB_CLIENT_ID?.trim() || ODYN_GITHUB_CLIENT_ID
+const TOKEN_FILE = join(homedir(), '.config', 'odyn-extension', 'github.json')
+const FORK_READY_ATTEMPTS = 20
+const FORK_READY_DELAY_MS = 3000
+
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms))
+
+/** Opens a web page in the user's browser. Best effort. */
+function openInBrowser(url) {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
+  try {
+    spawn(command, args, { stdio: 'ignore', detached: true }).unref()
+  } catch (error) {
+    console.warn(`Couldn't open the browser (${error instanceof Error ? error.message : String(error)}). Open ${url} yourself.`)
+  }
+}
+
+function readSavedToken() {
+  if (!existsSync(TOKEN_FILE)) return null
+  try {
+    const saved = JSON.parse(readFileSync(TOKEN_FILE, 'utf8'))
+    return typeof saved.token === 'string' && saved.token !== '' ? saved.token : null
+  } catch (error) {
+    console.warn(`Ignoring an unreadable saved sign-in: ${error instanceof Error ? error.message : String(error)}`)
+    return null
+  }
+}
+
+function saveToken(token) {
+  mkdirSync(dirname(TOKEN_FILE), { recursive: true })
+  writeFileSync(TOKEN_FILE, `${JSON.stringify({ token })}\n`, { mode: 0o600 })
+  chmodSync(TOKEN_FILE, 0o600)
+}
+
+/** The GitHub CLI's token, when it is installed and signed in. */
+function ghCliToken() {
+  try {
+    const token = execFileSync('gh', ['auth', 'token'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    return token === '' ? null : token
+  } catch {
+    return null
+  }
+}
+
+/** Signs in through the browser: shows a short code, the user approves it on github.com. */
+async function deviceSignIn() {
+  if (GITHUB_CLIENT_ID === '') {
+    throw new Error('Sign in to GitHub first: install the GitHub CLI and run `gh auth login`, or set GITHUB_TOKEN.')
+  }
+  const start = await fetch('https://github.com/login/device/code', {
+    method: 'POST',
+    headers: { accept: 'application/json', 'content-type': 'application/json' },
+    body: JSON.stringify({ client_id: GITHUB_CLIENT_ID, scope: 'public_repo' }),
+  })
+  const code = await start.json()
+  if (!start.ok || typeof code.device_code !== 'string') {
+    throw new Error(`GitHub sign-in couldn't start: ${code.error_description ?? code.error ?? start.status}`)
+  }
+  console.log(`\nSign in to GitHub: enter the code ${code.user_code} at ${code.verification_uri}`)
+  openInBrowser(code.verification_uri)
+  let interval = (code.interval ?? 5) * 1000
+  const deadline = Date.now() + (code.expires_in ?? 900) * 1000
+  while (Date.now() < deadline) {
+    await sleep(interval)
+    const poll = await fetch('https://github.com/login/oauth/access_token', {
+      method: 'POST',
+      headers: { accept: 'application/json', 'content-type': 'application/json' },
+      body: JSON.stringify({ client_id: GITHUB_CLIENT_ID, device_code: code.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }),
+    })
+    const result = await poll.json()
+    if (typeof result.access_token === 'string') return result.access_token
+    if (result.error === 'slow_down') interval += 5000
+    else if (result.error !== 'authorization_pending') throw new Error(`GitHub sign-in failed: ${result.error_description ?? result.error}`)
+  }
+  throw new Error('GitHub sign-in timed out. Run the command again.')
+}
+
+/**
+ * A GitHub token: `GITHUB_TOKEN`, then a saved sign-in, then the GitHub CLI,
+ * and finally a fresh sign-in through the browser.
+ */
+export async function getToken() {
+  const fromEnv = process.env.GITHUB_TOKEN?.trim()
+  if (fromEnv) return fromEnv
+  const saved = readSavedToken()
+  if (saved) return saved
+  const fromCli = ghCliToken()
+  if (fromCli) return fromCli
+  const fresh = await deviceSignIn()
+  saveToken(fresh)
+  return fresh
+}
+
+/** Forgets the saved sign-in, e.g. after GitHub rejects it. */
+export function forgetToken() {
+  if (existsSync(TOKEN_FILE)) writeFileSync(TOKEN_FILE, '{}\n', { mode: 0o600 })
+}
+
+/** A small GitHub API client. Throws a readable error on any failure. */
+export function githubClient(token) {
+  return async function request(method, path, body) {
+    const response = await fetch(`${API}${path}`, {
+      method,
+      headers: {
+        accept: 'application/vnd.github+json',
+        'x-github-api-version': '2022-11-28',
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+    if (response.status === 204) return null
+    const text = await response.text()
+    const data = text === '' ? null : JSON.parse(text)
+    if (!response.ok) {
+      const error = new Error(`GitHub said ${response.status} for ${method} ${path}: ${data?.message ?? text}`)
+      error.status = response.status
+      throw error
+    }
+    return data
+  }
+}
+
+/** Every file in the public repo's extension folder, as `{ path, sha }` relative to it. */
+export async function upstreamFiles(request, extensionId) {
+  const branch = await request('GET', `/repos/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/branches/${UPSTREAM_BRANCH}`)
+  const tree = await request('GET', `/repos/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/git/trees/${branch.commit.sha}?recursive=1`)
+  const prefix = `extensions/${extensionId}/`
+  const files = tree.tree
+    .filter((entry) => entry.type === 'blob' && entry.path.startsWith(prefix))
+    .map((entry) => ({ path: entry.path.slice(prefix.length), sha: entry.sha }))
+  return { commitSha: branch.commit.sha, treeSha: branch.commit.commit.tree.sha, files }
+}
+
+/** Makes sure the user has their own copy of the public repo, up to date. Returns its owner. */
+export async function ensureFork(request, login) {
+  try {
+    await request('GET', `/repos/${login}/${UPSTREAM_REPO}`)
+  } catch (error) {
+    if (error.status !== 404) throw error
+    console.log(`Making your copy of ${UPSTREAM_OWNER}/${UPSTREAM_REPO} on GitHub…`)
+    await request('POST', `/repos/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/forks`, { default_branch_only: true })
+    for (let attempt = 0; attempt < FORK_READY_ATTEMPTS; attempt += 1) {
+      await sleep(FORK_READY_DELAY_MS)
+      try {
+        await request('GET', `/repos/${login}/${UPSTREAM_REPO}/branches/${UPSTREAM_BRANCH}`)
+        return login
+      } catch (pollError) {
+        if (pollError.status !== 404 && pollError.status !== 409) throw pollError
+      }
+    }
+    throw new Error('GitHub is still making your copy of the repo. Try again in a minute.')
+  }
+  await request('POST', `/repos/${login}/${UPSTREAM_REPO}/merge-upstream`, { branch: UPSTREAM_BRANCH }).catch((error) => {
+    console.warn(`Couldn't bring your copy up to date first (${error.message}). Carrying on.`)
+  })
+  return login
+}
+
+/** Downloads one file of the public repo's main branch. */
+export async function downloadUpstreamFile(path) {
+  const url = `https://raw.githubusercontent.com/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/${UPSTREAM_BRANCH}/${path.split('/').map(encodeURIComponent).join('/')}`
+  const response = await fetch(url)
+  if (!response.ok) throw new Error(`Couldn't download ${path} (${response.status}).`)
+  return Buffer.from(await response.arrayBuffer())
+}

package/cli/odyn-extension.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * odyn-extension — make, test and publish Odyn extensions.
+ *
+ *   odyn-extension create <name>   start a new extension in a new folder
+ *   odyn-extension dev             build, then rebuild on every save (Odyn reloads it)
+ *   odyn-extension build           build once into dist/
+ *   odyn-extension check           check the manifest
+ *   odyn-extension pull <id>       download a published extension's source to work on it
+ *   odyn-extension publish         send this extension to the Marketplace as a pull request
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, watch, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { userInfo } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { buildExtension, checkExtension, readPackage } from './build.mjs'
+import {
+  UPSTREAM_BRANCH,
+  UPSTREAM_OWNER,
+  UPSTREAM_REPO,
+  downloadUpstreamFile,
+  ensureFork,
+  forgetToken,
+  getToken,
+  githubClient,
+  upstreamFiles,
+} from './github.mjs'
+import { starterFiles } from '../dist/index.js'
+
+const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const KIT_VERSION = JSON.parse(readFileSync(join(KIT_ROOT, 'package.json'), 'utf8')).version
+/** Saves that land within this window become one rebuild. */
+const REBUILD_DELAY_MS = 150
+/** Never sent to the public repo: installed packages, build output, local clutter. */
+const UNPUBLISHED = new Set(['node_modules', 'dist', 'build', '.git', '.DS_Store', 'bun.lock', 'bun.lockb', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'])
+/** A single file bigger than this is refused; the download as a whole is capped by the repo. */
+const MAX_PUBLISHED_FILE_BYTES = 5 * 1024 * 1024
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+const USAGE = `odyn-extension — make, test and publish Odyn extensions
+
+  create <name>   start a new extension in a new folder
+  dev             build, then rebuild on every save (Odyn reloads it)
+  build           build once into dist/
+  check           check the manifest
+  pull <id>       download a published extension's source to work on it
+  publish         send this extension to the Marketplace as a pull request
+
+Docs: https://www.odyn.build/docs/extensions`
+
+/** "Standup notes!" → "standup-notes". */
+function toId(name) {
+  return name.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+/** The user's name from git, or their login name. */
+function authorName() {
+  try {
+    const name = execFileSync('git', ['config', 'user.name'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    if (name !== '') return name
+  } catch {
+    // No git, or no name set — fall back below.
+  }
+  return userInfo().username
+}
+
+function writeFiles(folder, files) {
+  for (const [path, content] of Object.entries(files)) {
+    const target = join(folder, path)
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, content)
+  }
+}
+
+function create(args) {
+  const name = args.join(' ').trim()
+  if (name === '') throw new Error('Give the extension a name, e.g. `odyn-extension create "Standup notes"`.')
+  const id = toId(name)
+  if (!ID_PATTERN.test(id)) throw new Error(`"${name}" needs at least one letter or digit.`)
+  const folder = resolve(id)
+  if (existsSync(folder) && readdirSync(folder).length > 0) throw new Error(`${folder} already exists and isn't empty.`)
+  const title = name === id ? name.replace(/-/g, ' ').replace(/^./, (letter) => letter.toUpperCase()) : name
+  writeFiles(folder, starterFiles({ id, title, author: authorName(), kitVersion: `^${KIT_VERSION}` }))
+  console.log(`Made ${relative(process.cwd(), folder) || '.'}/
+
+Next:
+  cd ${id}
+  bun install
+  bun run dev
+
+Then in Odyn: Marketplace → Extensions → Install from folder, and pick the folder.`)
+}
+
+/** The extension folder the command was run in. */
+function currentExtension() {
+  const folder = process.cwd()
+  if (!existsSync(join(folder, 'package.json'))) throw new Error('Run this inside an extension folder (one with a package.json).')
+  return folder
+}
+
+async function buildOnce(folder) {
+  const started = Date.now()
+  const { id, version } = await buildExtension(folder)
+  console.log(`Built ${id} ${version} in ${Date.now() - started} ms`)
+}
+
+async function dev() {
+  const folder = currentExtension()
+  await buildOnce(folder)
+  console.log('Watching for changes. Odyn reloads the extension after each build. Press Ctrl+C to stop.')
+  let timer = null
+  let building = false
+  let again = false
+  const rebuild = async () => {
+    if (building) {
+      again = true
+      return
+    }
+    building = true
+    try {
+      await buildOnce(folder)
+    } catch (error) {
+      console.error(`Build failed: ${error instanceof Error ? error.message : String(error)}`)
+    } finally {
+      building = false
+      if (again) {
+        again = false
+        void rebuild()
+      }
+    }
+  }
+  watch(folder, { recursive: true }, (_event, file) => {
+    if (typeof file !== 'string') return
+    const top = file.split(sep)[0]
+    if (UNPUBLISHED.has(top)) return
+    if (timer !== null) clearTimeout(timer)
+    timer = setTimeout(() => { timer = null; void rebuild() }, REBUILD_DELAY_MS)
+  })
+}
+
+function check() {
+  const problems = checkExtension(currentExtension())
+  if (problems.length > 0) throw new Error(problems.join('\n'))
+  console.log('The manifest looks good.')
+}
+
+async function pull(args) {
+  const id = args[0]
+  if (!id || !ID_PATTERN.test(id)) throw new Error('Give the extension id, e.g. `odyn-extension pull standup-notes`.')
+  const folder = resolve(id)
+  if (existsSync(folder) && readdirSync(folder).length > 0) throw new Error(`${folder} already exists and isn't empty.`)
+  const request = githubClient(process.env.GITHUB_TOKEN?.trim() || null)
+  const { files } = await upstreamFiles(request, id)
+  if (files.length === 0) throw new Error(`There's no extension called "${id}" in ${UPSTREAM_OWNER}/${UPSTREAM_REPO}.`)
+  for (const file of files) {
+    const target = join(folder, file.path)
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, await downloadUpstreamFile(`extensions/${id}/${file.path}`))
+  }
+  // Extensions in the repo share its tools; on its own the folder needs the kit
+  // and the usual shortcuts.
+  const pkg = readPackage(folder)
+  const starter = JSON.parse(starterFiles({ id, title: id, author: '', kitVersion: `^${KIT_VERSION}` })['package.json'])
+  pkg.scripts = { ...starter.scripts, ...pkg.scripts }
+  pkg.dependencies = { ...starter.dependencies, ...pkg.dependencies }
+  writeFileSync(join(folder, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`)
+  console.log(`Downloaded ${files.length} files into ${id}/
+
+Next:
+  cd ${id}
+  bun install
+  bun run dev
+
+When you're done, \`bun run publish\` sends your changes for review.`)
+}
+
+/** Every file to publish, relative to the folder, skipping installed packages and build output. */
+function publishableFiles(folder) {
+  const files = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (UNPUBLISHED.has(entry.name)) continue
+      const path = join(dir, entry.name)
+      if (entry.isDirectory()) walk(path)
+      else if (entry.isFile()) files.push(relative(folder, path).split(sep).join('/'))
+    }
+  }
+  walk(folder)
+  return files.sort()
+}
+
+async function publish() {
+  const folder = currentExtension()
+  const problems = checkExtension(folder)
+  if (problems.length > 0) throw new Error(`Fix these before publishing:\n${problems.join('\n')}`)
+  // Building first catches mistakes before anyone has to review them.
+  await buildOnce(folder)
+
+  let token = await getToken()
+  let request = githubClient(token)
+  let user
+  try {
+    user = await request('GET', '/user')
+  } catch (error) {
+    if (error.status !== 401) throw error
+    forgetToken()
+    token = await getToken()
+    request = githubClient(token)
+    user = await request('GET', '/user')
+  }
+  const login = user.login
+
+  // The person publishing looks after the extension, unless someone already does.
+  const pkg = readPackage(folder)
+  const id = pkg.odyn.id
+  const upstream = await upstreamFiles(request, id)
+  const isNew = upstream.files.length === 0
+  if (!Array.isArray(pkg.odyn.owners) || pkg.odyn.owners.length === 0) {
+    pkg.odyn.owners = [login]
+    writeFileSync(join(folder, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`)
+    console.log(`Added you (${login}) as the owner in package.json.`)
+  }
+
+  const fork = await ensureFork(request, login)
+  const local = publishableFiles(folder)
+  for (const path of local) {
+    if (statSync(join(folder, path)).size > MAX_PUBLISHED_FILE_BYTES) throw new Error(`${path} is over 5 MB. Leave large files out.`)
+  }
+  const prefix = `extensions/${id}/`
+  const entries = []
+  for (const path of local) {
+    const blob = await request('POST', `/repos/${fork}/${UPSTREAM_REPO}/git/blobs`, {
+      content: readFileSync(join(folder, path)).toString('base64'),
+      encoding: 'base64',
+    })
+    entries.push({ path: `${prefix}${path}`, mode: '100644', type: 'blob', sha: blob.sha })
+  }
+  // Files that were published before but are gone now are removed.
+  const kept = new Set(local)
+  for (const file of upstream.files) {
+    if (!kept.has(file.path)) entries.push({ path: `${prefix}${file.path}`, mode: '100644', type: 'blob', sha: null })
+  }
+  const tree = await request('POST', `/repos/${fork}/${UPSTREAM_REPO}/git/trees`, { base_tree: upstream.treeSha, tree: entries })
+  if (tree.sha === upstream.treeSha) {
+    console.log('Nothing has changed since the published version.')
+    return
+  }
+  const version = pkg.version
+  const message = isNew ? `Add ${pkg.odyn.title} ${version}` : `Update ${pkg.odyn.title} to ${version}`
+  const commit = await request('POST', `/repos/${fork}/${UPSTREAM_REPO}/git/commits`, { message, tree: tree.sha, parents: [upstream.commitSha] })
+  const branch = `extension/${id}`
+  try {
+    await request('PATCH', `/repos/${fork}/${UPSTREAM_REPO}/git/refs/heads/${branch}`, { sha: commit.sha, force: true })
+  } catch (error) {
+    if (error.status !== 404 && error.status !== 422) throw error
+    await request('POST', `/repos/${fork}/${UPSTREAM_REPO}/git/refs`, { ref: `refs/heads/${branch}`, sha: commit.sha })
+  }
+
+  const open = await request('GET', `/repos/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/pulls?state=open&head=${encodeURIComponent(`${fork}:${branch}`)}`)
+  if (open.length > 0) {
+    console.log(`Updated your pull request: ${open[0].html_url}`)
+    return
+  }
+  const body = [
+    isNew ? `Adds **${pkg.odyn.title}** (\`${id}\`) ${version}.` : `Updates **${pkg.odyn.title}** (\`${id}\`) to ${version}.`,
+    '',
+    pkg.odyn.description,
+    '',
+    `Permissions: ${pkg.odyn.permissions.length === 0 ? 'none' : pkg.odyn.permissions.map((permission) => `\`${permission}\``).join(', ')}`,
+    '',
+    `Published with \`odyn-extension publish\` (kit ${KIT_VERSION}).`,
+  ].join('\n')
+  const pr = await request('POST', `/repos/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/pulls`, {
+    title: message,
+    head: `${fork}:${branch}`,
+    base: UPSTREAM_BRANCH,
+    body,
+    maintainer_can_modify: true,
+  })
+  console.log(`Opened a pull request: ${pr.html_url}
+Once it's reviewed and merged, ${pkg.odyn.title} appears in Odyn's Marketplace.
+To change it later, edit this folder and run \`bun run publish\` again.`)
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2)
+  switch (command) {
+    case 'create': return create(args)
+    case 'dev': return dev()
+    case 'build': return buildOnce(currentExtension())
+    case 'check': return check()
+    case 'pull': return pull(args)
+    case 'publish': return publish()
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(USAGE)
+      return undefined
+    default:
+      throw new Error(`Unknown command "${command}".\n\n${USAGE}`)
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})
+

package/dist/index.d.ts

@@ -7,6 +7,14 @@ export declare const EXTENSION_PERMISSIONS: readonly ["chats:read", "projects:re
 export type ExtensionPermission = (typeof EXTENSION_PERMISSIONS)[number];
 /** Permissions only extensions made by Odyn may ask for. */
 export declare const OFFICIAL_ONLY_PERMISSIONS: readonly ExtensionPermission[];
+/**
+ * The extensions made by Odyn. Only these may run Mac programs or a background
+ * helper, and only these show as "Official". Everything else in Odyn's
+ * Marketplace — however it got there — follows the normal rules.
+ */
+export declare const ODYN_EXTENSION_IDS: readonly string[];
+/** Whether an extension id is one of Odyn's own. */
+export declare function isOdynExtensionId(id: string): boolean;
 /** Systems an extension can say it runs on. Leave out to run everywhere. */
 export declare const EXTENSION_PLATFORMS: readonly ["darwin", "linux", "win32"];
 export type ExtensionPlatform = (typeof EXTENSION_PLATFORMS)[number];
@@ -142,6 +150,11 @@ export interface ExtensionManifest {
     readonly helper?: ExtensionHelper;
     /** A guide and permission-checked commands for the agent. */
     readonly agent?: ExtensionAgent;
+    /**
+     * GitHub usernames of the people who look after it. Changes to the
+     * extension in the public repo need one of them (or Odyn) to approve.
+     */
+    readonly owners?: readonly string[];
 }
 export interface ExtensionAction {
     readonly id: string;
@@ -262,9 +275,10 @@ export declare function defineExtension(definition: ExtensionDefinition): Extens
 /** Returns every problem with a manifest; an empty list means it is fine. */
 export interface ManifestCheckOptions {
     /**
-     * Made by Odyn and shipped inside the app. An official extension may be
-     * nothing but an on/off switch for a feature built into Odyn, so it doesn't
-     * need a command, page, helper or agent section.
+     * One of Odyn's own extensions (`ODYN_EXTENSION_IDS`). These may run Mac
+     * programs through a background helper, and may be nothing but an on/off
+     * switch for a feature built into Odyn, so they don't need a command, page,
+     * helper or agent section.
      */
     readonly official?: boolean;
 }
@@ -490,3 +504,13 @@ export interface HelperBridge {
 }
 /** The one call a helper's script makes. Anywhere but Odyn it just hands the definition back. */
 export declare function defineHelper(definition: HelperDefinition): HelperDefinition;
+export interface StarterOptions {
+    /** Lowercase words joined by dashes, e.g. "standup-notes". */
+    readonly id: string;
+    readonly title: string;
+    readonly author: string;
+    /** The kit version range to depend on, e.g. "^0.2.0". */
+    readonly kitVersion: string;
+}
+/** The files of a working extension with one command, keyed by path. */
+export declare function starterFiles(options: StarterOptions): Readonly<Record<string, string>>;

package/dist/index.js

@@ -33,6 +33,24 @@ export const EXTENSION_PERMISSIONS = [
 ];
 /** Permissions only extensions made by Odyn may ask for. */
 export const OFFICIAL_ONLY_PERMISSIONS = ['programs:run'];
+/**
+ * The extensions made by Odyn. Only these may run Mac programs or a background
+ * helper, and only these show as "Official". Everything else in Odyn's
+ * Marketplace — however it got there — follows the normal rules.
+ */
+export const ODYN_EXTENSION_IDS = [
+    'agent-inboxes',
+    'computer-use',
+    'design-skills',
+    'fast-browser',
+    'message-outline',
+    'phones',
+    'scratchpad',
+];
+/** Whether an extension id is one of Odyn's own. */
+export function isOdynExtensionId(id) {
+    return ODYN_EXTENSION_IDS.includes(id);
+}
 /** Systems an extension can say it runs on. Leave out to run everywhere. */
 export const EXTENSION_PLATFORMS = ['darwin', 'linux', 'win32'];
 /** Where an extension can show up inside Odyn. */
@@ -98,6 +116,8 @@ export function defineExtension(definition) {
 }
 // --- Checking a manifest --------------------------------------------------
 const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A GitHub username: letters, digits and single dashes, up to 39 characters. */
+const GITHUB_USERNAME_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
 const ENTRY_PATTERN = /^(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+\.html$/;
 function surfaceProblems(surfaces, apiVersion) {
     if (surfaces.length === 0)
@@ -269,7 +289,12 @@ export function validateManifest(value, options = {}) {
             problems.push(`Unknown permissions: ${unknown.join(', ')}.`);
         if (permissions.includes('network') && !(manifest.allowedHosts?.length))
             problems.push('`network` needs at least one entry in `allowedHosts`.');
+        const odynOnly = permissions.filter((permission) => OFFICIAL_ONLY_PERMISSIONS.includes(permission));
+        if (!options.official && odynOnly.length > 0)
+            problems.push(`\`${odynOnly.join('`, `')}\` is only for extensions made by Odyn.`);
     }
+    if (!options.official && manifest.helper !== undefined)
+        problems.push('A `helper` is only for extensions made by Odyn.');
     const surfaces = manifest.surfaces ?? [];
     if (!Array.isArray(surfaces))
         problems.push('`surfaces` must be a list.');
@@ -283,6 +308,11 @@ export function validateManifest(value, options = {}) {
         }
     }
     problems.push(...helperProblems(manifest, apiVersion), ...agentProblems(manifest, apiVersion));
+    if (manifest.owners !== undefined) {
+        if (!Array.isArray(manifest.owners) || manifest.owners.some((owner) => typeof owner !== 'string' || !GITHUB_USERNAME_PATTERN.test(owner))) {
+            problems.push('`owners` must be a list of GitHub usernames.');
+        }
+    }
     const hasSurfaces = Array.isArray(surfaces) && surfaces.length > 0;
     const hasHelper = manifest.helper !== undefined;
     // From version 4 a guide for the agent is enough on its own.
@@ -485,3 +515,57 @@ export function defineHelper(definition) {
     settle(null, () => definition.start(odyn));
     return definition;
 }
+/** The files of a working extension with one command, keyed by path. */
+export function starterFiles(options) {
+    const { id, title, author, kitVersion } = options;
+    const manifest = {
+        name: `odyn-extension-${id}`,
+        version: '1.0.0',
+        private: true,
+        type: 'module',
+        scripts: { dev: 'odyn-extension dev', build: 'odyn-extension build', check: 'odyn-extension check', publish: 'odyn-extension publish' },
+        dependencies: { '@odyn-app/api': kitVersion },
+        odyn: {
+            id,
+            title,
+            description: `${title} for Odyn.`,
+            author,
+            apiVersion: EXTENSION_API_VERSION,
+            permissions: [],
+            commands: [{ name: 'say-hello', title: 'Say hello', placement: 'sidebarPanel' }],
+        },
+    };
+    return {
+        'package.json': `${JSON.stringify(manifest, null, 2)}\n`,
+        'src/index.ts': [
+            "import { defineExtension } from '@odyn-app/api'",
+            '',
+            'defineExtension({',
+            "  commands: {",
+            `    'say-hello': async () => ({ type: 'detail', markdown: ${JSON.stringify(`Hello from ${title}.`)} }),`,
+            '  },',
+            '})',
+            '',
+        ].join('\n'),
+        'tsconfig.json': `${JSON.stringify({
+            compilerOptions: { target: 'es2022', module: 'esnext', moduleResolution: 'bundler', jsx: 'react-jsx', strict: true, noEmit: true, skipLibCheck: true, lib: ['es2022', 'dom'] },
+            include: ['src'],
+        }, null, 2)}\n`,
+        '.gitignore': 'node_modules\ndist\n',
+        'README.md': [
+            `# ${title}`,
+            '',
+            'An Odyn extension.',
+            '',
+            '```bash',
+            'bun install',
+            'bun run dev      # rebuilds on every save; Odyn reloads it',
+            'bun run publish  # sends it to the Marketplace for review',
+            '```',
+            '',
+            'In Odyn, open Marketplace → Extensions → Install from folder and pick this folder.',
+            'Docs: https://www.odyn.build/docs/extensions',
+            '',
+        ].join('\n'),
+    };
+}

package/dist/ui/orb/orb-frame-clock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One shared clock that moves every spinning orb forward a few times a second.
+ *
+ * Left to itself, a CSS animation makes the browser redraw the whole window 60
+ * times a second for as long as it runs. While a reply is streaming, that
+ * redraw cost about 40% of a processor core in testing — and one 3px orb cost
+ * as much as four, because the price is the redraw itself, not the dots.
+ *
+ * So the orbs' CSS animations are paused as soon as they start, and this clock
+ * moves them to the right moment ORB_FRAMES_PER_SECOND times a second. Each
+ * style keeps its exact shape and easing; only the number of redraws drops.
+ * Between ticks nothing changes, and the browser skips the redraw.
+ */
+export declare const ORB_FRAMES_PER_SECOND = 12;
+/** Marks an orb's outer element, so a starting animation can be traced to one. */
+export declare const ORB_ROOT_ATTRIBUTE = "data-orb";
+/** Present on an orb held on its opening frame; the clock leaves those alone. */
+export declare const ORB_PAUSED_ATTRIBUTE = "data-orb-paused";
+/** Moves every clocked animation to where it should be at `now`. */
+export declare function tickOrbClock(now: number): void;
+/**
+ * Hands these animations to the shared clock, carrying on from wherever each
+ * one already is. Handing over one that is already clocked does nothing.
+ */
+export declare function clockOrbAnimations(animations: readonly Animation[], now?: number): void;
+/** Takes these animations off the clock. They stay paused where they are. */
+export declare function releaseOrbAnimations(animations: readonly Animation[]): void;
+/**
+ * Called by each orb while it is on screen. The first one starts listening for
+ * orb animations; the last one to leave stops. Returns the matching "leave".
+ */
+export declare function watchOrbAnimations(): () => void;
+/** How many animations the clock is driving — for tests. */
+export declare function clockedOrbAnimationCount(): number;

package/dist/ui/orb/orb-frame-clock.js

@@ -0,0 +1,110 @@
+/**
+ * One shared clock that moves every spinning orb forward a few times a second.
+ *
+ * Left to itself, a CSS animation makes the browser redraw the whole window 60
+ * times a second for as long as it runs. While a reply is streaming, that
+ * redraw cost about 40% of a processor core in testing — and one 3px orb cost
+ * as much as four, because the price is the redraw itself, not the dots.
+ *
+ * So the orbs' CSS animations are paused as soon as they start, and this clock
+ * moves them to the right moment ORB_FRAMES_PER_SECOND times a second. Each
+ * style keeps its exact shape and easing; only the number of redraws drops.
+ * Between ticks nothing changes, and the browser skips the redraw.
+ */
+export const ORB_FRAMES_PER_SECOND = 12;
+const ORB_FRAME_INTERVAL_MS = 1000 / ORB_FRAMES_PER_SECOND;
+/** Marks an orb's outer element, so a starting animation can be traced to one. */
+export const ORB_ROOT_ATTRIBUTE = 'data-orb';
+/** Present on an orb held on its opening frame; the clock leaves those alone. */
+export const ORB_PAUSED_ATTRIBUTE = 'data-orb-paused';
+/** Each clocked animation, with when its own timeline started (`performance.now()` scale). */
+const clockedAnimations = new Map();
+let clockTimer = null;
+let mountedOrbCount = 0;
+function readCurrentTime(animation) {
+    const { currentTime } = animation;
+    return typeof currentTime === 'number' ? currentTime : 0;
+}
+function stopClockIfIdle() {
+    if (clockedAnimations.size > 0 || clockTimer === null)
+        return;
+    clearInterval(clockTimer);
+    clockTimer = null;
+}
+/** Moves every clocked animation to where it should be at `now`. */
+export function tickOrbClock(now) {
+    for (const [animation, origin] of clockedAnimations) {
+        // The stylesheet removed it (the orb left the page, or reduce-motion was
+        // switched on), so stop driving it — setting its time would revive it.
+        if (animation.playState === 'idle') {
+            clockedAnimations.delete(animation);
+            continue;
+        }
+        animation.currentTime = now - origin;
+    }
+    stopClockIfIdle();
+}
+function tickWhenVisible() {
+    // A hidden window has nothing to show; the next visible tick jumps each
+    // animation straight to the right moment.
+    if (typeof document !== 'undefined' && document.hidden)
+        return;
+    tickOrbClock(performance.now());
+}
+/**
+ * Hands these animations to the shared clock, carrying on from wherever each
+ * one already is. Handing over one that is already clocked does nothing.
+ */
+export function clockOrbAnimations(animations, now = performance.now()) {
+    for (const animation of animations) {
+        if (animation.playState === 'idle' || clockedAnimations.has(animation))
+            continue;
+        clockedAnimations.set(animation, now - readCurrentTime(animation));
+        animation.pause();
+    }
+    if (clockedAnimations.size > 0)
+        clockTimer ??= setInterval(tickWhenVisible, ORB_FRAME_INTERVAL_MS);
+}
+/** Takes these animations off the clock. They stay paused where they are. */
+export function releaseOrbAnimations(animations) {
+    for (const animation of animations)
+        clockedAnimations.delete(animation);
+    stopClockIfIdle();
+}
+/**
+ * Some orb animations start after the orb first appears — a card opening, a
+ * row scrolling back into view. Catch each one the moment it starts.
+ */
+function handleAnimationStart(event) {
+    const { target } = event;
+    if (!(target instanceof Element))
+        return;
+    if (target.closest(`[${ORB_ROOT_ATTRIBUTE}]`) === null)
+        return;
+    if (target.closest(`[${ORB_PAUSED_ATTRIBUTE}]`) !== null)
+        return;
+    clockOrbAnimations(target
+        .getAnimations()
+        .filter((animation) => animation instanceof CSSAnimation && animation.animationName === event.animationName));
+}
+/**
+ * Called by each orb while it is on screen. The first one starts listening for
+ * orb animations; the last one to leave stops. Returns the matching "leave".
+ */
+export function watchOrbAnimations() {
+    if (typeof document === 'undefined')
+        return () => { };
+    mountedOrbCount += 1;
+    if (mountedOrbCount === 1)
+        document.addEventListener('animationstart', handleAnimationStart, true);
+    return () => {
+        mountedOrbCount -= 1;
+        if (mountedOrbCount === 0) {
+            document.removeEventListener('animationstart', handleAnimationStart, true);
+        }
+    };
+}
+/** How many animations the clock is driving — for tests. */
+export function clockedOrbAnimationCount() {
+    return clockedAnimations.size;
+}

package/dist/ui/orb/orb.d.ts

@@ -1,4 +1,4 @@
-import type { CSSProperties, ReactElement } from 'react';
+import { type CSSProperties, type ReactElement } from 'react';
 import { type OrbVariant } from './orb-types';
 export interface OrbProps {
     readonly variant?: OrbVariant;

package/dist/ui/orb/orb.js

@@ -1,5 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
 import baseStyles from './orb-base.module.css';
 import helixStyles from './orb-helix.module.css';
 import latticeStyles from './orb-lattice.module.css';
@@ -8,6 +9,7 @@ import lensPrimaryStyles from './orb-lens-primary.module.css';
 import lensSecondaryStyles from './orb-lens-secondary.module.css';
 import morphStyles from './orb-morph.module.css';
 import ringStyles from './orb-ring.module.css';
+import { clockOrbAnimations, ORB_PAUSED_ATTRIBUTE, ORB_ROOT_ATTRIBUTE, releaseOrbAnimations, watchOrbAnimations, } from './orb-frame-clock';
 import { globeDots } from './orb-helix-geometry';
 import { latticeCells } from './orb-lattice-geometry';
 import { morphDots } from './orb-morph-geometry';
@@ -23,7 +25,23 @@ function lensVariantClass(variant) {
 }
 export function Orb({ variant = 'S1', size = DEFAULT_SIZE, label, decorative = false, paused = false, className, style, }) {
     const text = label ?? `${ORB_TASKS[variant]}…`;
-    return (_jsx("span", { className: className ? `${baseStyles.root} ${className}` : baseStyles.root, "data-orb-paused": paused ? '' : undefined, style: style, children: _jsx("span", { className: baseStyles.glyph, role: decorative ? undefined : 'img', "aria-label": decorative ? undefined : text, "aria-hidden": decorative ? true : undefined, style: { width: size, height: size, '--orb-k': size / STAGE }, children: isLattice(variant) ? (_jsx("span", { className: latticeStyles.lattice, "data-variant": variant, children: latticeCells(variant).map((cell) => (_jsx("span", { className: latticeStyles.cell, "data-still": cell.still ? '' : undefined, "data-mid": cell.mid ? '' : undefined, style: {
+    const rootRef = useRef(null);
+    // Hand the running animations to the shared low-rate clock; any that start
+    // later are caught as they start. A paused orb is left to the stylesheet,
+    // which holds it on its opening frame. A new variant brings new animations,
+    // so they are handed over again.
+    useEffect(() => {
+        const root = rootRef.current;
+        if (paused || root === null)
+            return;
+        const stopWatching = watchOrbAnimations();
+        clockOrbAnimations(root.getAnimations({ subtree: true }));
+        return () => {
+            stopWatching();
+            releaseOrbAnimations(root.getAnimations({ subtree: true }));
+        };
+    }, [paused, variant]);
+    return (_jsx("span", { ref: rootRef, className: className ? `${baseStyles.root} ${className}` : baseStyles.root, [ORB_ROOT_ATTRIBUTE]: '', [ORB_PAUSED_ATTRIBUTE]: paused ? '' : undefined, style: style, children: _jsx("span", { className: baseStyles.glyph, role: decorative ? undefined : 'img', "aria-label": decorative ? undefined : text, "aria-hidden": decorative ? true : undefined, style: { width: size, height: size, '--orb-k': size / STAGE }, children: isLattice(variant) ? (_jsx("span", { className: latticeStyles.lattice, "data-variant": variant, children: latticeCells(variant).map((cell) => (_jsx("span", { className: latticeStyles.cell, "data-still": cell.still ? '' : undefined, "data-mid": cell.mid ? '' : undefined, style: {
                         left: cell.left,
                         top: cell.top,
                         animationDelay: `${cell.delay}ms`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odyn-app/api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The public building kit for Odyn extensions.",
   "license": "MIT",
   "homepage": "https://github.com/New-Genre/odyn-extensions",
@@ -24,10 +24,12 @@
       "types": "./dist/ui/index.d.ts",
       "default": "./dist/ui/index.js"
     },
-    "./theme.css": "./dist/ui/theme.css"
+    "./theme.css": "./dist/ui/theme.css",
+    "./build": "./cli/build.mjs"
   },
   "files": [
     "dist",
+    "cli",
     "README.md"
   ],
   "sideEffects": [
@@ -43,16 +45,21 @@
   "dependencies": {
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "tailwind-merge": "^3.6.0"
+    "tailwind-merge": "^3.6.0",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@vitejs/plugin-react": "^6.0.4",
+    "tailwindcss": "^4.3.3",
+    "vite": "^8.1.5"
   },
   "peerDependencies": {
-    "react": ">=19",
-    "tailwindcss": ">=4.3"
+    "react": ">=19"
   },
   "devDependencies": {
     "@types/react": "^19.2.17",
     "react": "^19.2.8",
-    "tailwindcss": "^4.3.3",
     "typescript": "^5.9.3"
+  },
+  "bin": {
+    "odyn-extension": "cli/odyn-extension.mjs"
   }
 }