product-app-api

Product App API Skill

Use this skill for Product App runtime code and platform capability work. Prefer current tool output, scaffold files, and package validation results over memory.

Runtime Model

• ui.js runs in the iframe/browser environment. It uses the DOM, standard browser APIs, ESM imports, and window.app.
• worker.js is optional backend logic running in a separate JavaScript Worker host. Custom app.call(method, params) calls only methods exported by worker.js.
• source_manifest.json describes entrypoints: uiEntry, optional workerEntry, styleEntries, and buildMode. Current built-in apps use nativeEsm.
• esm_dependencies.json is the browser import-map dependency array, not an object. Write [] when there are no dependencies.
• Extra source files are read from source/. Do not handwrite private_surface_sources; edit package source files.
• A Product App surface implementationRef must be app://<app-id>@<version>/surfaces/<surface-id>. Do not fall back to old bundle://surface-components/... refs.

window.app Capabilities

The runtime adapter exposes window.app. A common alias is:

const runtime = () => window.app || {};

Basic properties:

• app.appId
• app.appDataDir
• app.workspaceDir
• app.theme
• app.locale
• app.platform
• app.mode

Host capabilities:

• app.fs.readFile/writeFile/readdir/stat/mkdir/rm/copyFile/rename/appendFile
• app.shell.exec(command, opts)
• app.net.fetch(url, opts)
• app.os.info()
• app.storage.get(key) / app.storage.set(key, value)
• app.dialog.open/save/message
• app.clipboard.writeText/readText
• app.ai.complete/chat/cancel/getModels
• app.backend.call/cancel/status/cancelRun/cancelStaleRuns/turnText/onEvent/offEvent
• app.host.fillChatInput(text)
• app.deck.renderPage(opts)
• app.log.debug/info/warn/error
• app.onActivate/onDeactivate/onThemeChange/onLocaleChange
• app.i18n.t(key, params, fallback), app.i18n.setMessages(messages), app.i18n.onChange(fn)
• app.t(localeTable, fallback): selects text from { "zh-CN": "...", "en-US": "..." } using the current locale.
• app.on(event, fn) / app.off(event, fn): subscribes to runtime events, worker:*, backend:event, and similar events.
• app.ui: runtime UI Kit. UI details belong in product-app-ui-polish.