tarwin/tinyjsapp/skill

tinyjs new <dir>    # scaffold (zero dependencies)
tinyjs new <dir> --template react-ts|vue-ts|svelte-ts|solid-ts|preact-ts|lit-ts|alpine-ts|vanilla-ts|…
                    #   create-vite + tinyjs overlay: HMR dev server in the
                    #   native window, esbuild-bundled TS backend (npm pkgs ok).
                    #   No name = asks framework + language. --pm npm|pnpm|
                    #   yarn|bun|vp[:pnpm] (else asks; npm off a terminal),
                    #   --no-install. Agents: pass both flags — no prompts.
                    #   vp needs Vite+ ≥ 1.0. alpine = vanilla + Alpine.js.
tinyjs wrap <url>   # site wrapper: the site IS the app, origin-gated API
                    #   (--origins subdomains, --menubar [--panel], --top,
                    #   --external a.com, --ua, --force re-wraps in place)
tinyjs dev          # run with hot reload (frontend edits swap in place;
                    #   backend edits restart the process)
tinyjs build        # dist/<name> binary + dist/<Name>.app (codesigned)
                    #   --dmg installer image; --cli [name] terminal shim
                    #   --arch arm64|x86_64: macOS .app for that CPU (any Mac;
                    #   0.42+); --universal: one .app for both (needs the
                    #   Command Line Tools' lipo). Bare dist/<name> = host CPU
tinyjs publish      # build + dist/publish/<name>-<ver>.zip|tarball + manifest
tinyjs notarize     # macOS: notarytool submit + staple (--dmg re-makes dmg)
                    # publish/notarize take --arch too — repeat the build's
tinyjs doctor       # find why tinyjs or the project won't run (read-only;
                    #   exit 1 on any FAIL) — run it first when things break
tinyjs update       # update tinyjs itself (--check); also: uninstall, version
tinyjs update-project  # then, in the project: refresh THIS skill and the
                    #   types from the installed tinyjs (names every file
                    #   it changes; overwrites edits to them)
TINYJS_DEBUG=1 tinyjs dev   # trace every bridge message

tinyjs.json          { name, title, size, id, version, icon?,
                       minTinyjsVersion?,     // refuse older tinyjs with a
                                              // real message; `tinyjs new`
                                              // stamps its own version — raise
                                              // it for newer APIs you adopt
                       update?: { url: "https://…/manifest.json", auto? },
                       urlScheme?: "myapp", fileExtensions?: ["md"],
                       openFolders?: true, readAccess?: true | "/path",
                       userAgent?: "…", activation?: "accessory",
                       mainWindow?: false,  // no main window/WebView (tray agents)
                       offscreenRescue?: false, windowPlacement?: true,
                       contextMenu?: false, audioTap?: "app" | "system",
                       audioTapReason?: "why", about?: "menu",
                       attribution?: "…",  // About panel credit line (macOS);
                                           // assets/Credits.html|rtf wins
                       resources?: ["a.json", "dir/"],  // narrow resources/ (default: all)
                       executables?: ["my-cli.exe", "linux/"],  // narrow executables/ (default: all for this OS)
                       // macos.executableEntitlements: { "my-cli": ["com.apple.security.cs.allow-jit"] }
                       debug?: true | "open", browserAccelerators?: true,
                       permissions?: { microphone?: "why", camera?: "why",
                                       speechRecognition?: "why" },
                       chrome?: { frame, windowControls, windowControlsPos,
                                  transparent, vibrancy, squareCorners,
                                  acceptsFirstMouse, menu },
                       signIdentity?, notarize?: { profile },
                       backend?: "backend/main.ts",   // .ts → esbuild bundle;
                                      // default src/backend/main.{js,ts}, then
                                      // src/main.{js,ts} (pre-0.52), backend/main.{js,ts}
                       frontend?: { dir?, build, dist, dev, devUrl, reload? },
                                      // dir: plain page folder (default src/frontend);
                                      // reload: false = dev leaves reloads to your tool;
                                      // build/dev need the packages installed first
                       // wrapping a hosted site (recipes.md) — "url" replaces
                       // the local frontend, "api" gates what that origin may
                       // call. NEVER wrap a site you don't control without it.
                       url?: "https://app.example.com",
                       inject?: "src/shim.js",        // document-start, every page
                       downloads?: "auto" | "ask" | "deny",
                       popups?: "external" | "window" | "deny",
                       api?: "wrapper" | "none" | [...allowed] | { disable?, enable?, origins? },
                                      // false/"" = "none"; { enable } alone = only those
                       macos?/windows?/linux?: { …merged on top per OS }
                                      // macos.helpBook: "My Help" = folder in assets/ }
assets/              files the OS reads, by name: icon.png (1024×1024 app
                     icon), Credits.html|rtf|rtfd (macOS About), help book
                     folder (macOS Help menu). Older projects: icon.png and
                     Credits.html at the root still work
resources/           data the backend reads at runtime → (await app.paths()).resources
                     (the folder in dev, bundled copy in builds; null if none)
executables/         sidecar binaries → (await app.paths()).executables (flat). Ships
                     this OS's binaries from the top, overridden by name from
                     <os>/ then <os>-arm64|-x86_64/; signed into
                     Contents/Helpers on macOS
extras/              README, licence… for the person downloading: shipped
                     BESIDE the app (macOS dmg root, Windows/Linux app
                     folder), never inside it. Top level + <os>/ overrides
src/backend/main.js  backend
src/frontend/        index.html + assets — served as real files (file://),
                     so relative paths just work
src/shared/          code both sides import as '../shared/x.js' (same path
                     from backend and page, dev and build). Ships with the
                     page: no secrets, no tjs:* imports. Not available in
                     the pre-0.52 src/main.js layout

export const api = {
  // page calls tiny.api.call('readNotes', { dir }) — return resolves the
  // page's promise, throwing rejects it; meta.window = calling window id
  readNotes: async ({ dir }, app, meta) => { ... },
};
export function init(app) {
  app.push('event-name', data);            // page: tiny.api.on('event-name')
  // app mirrors the page: app.window(id).*, app.win.open, app.menu.*,
  // app.tray.*, app.audio.sampler.*, app.clipboard.*, app.store.*,
  // app.paths(), app.system.*, notify, quit, … — main-window ops also sit at
  // the top level (app.setTitle, app.setChrome, …); see references/api.md
}
// other exports the scaffold wires, each (info, app): onMenu, onTray (id
// null = bare icon click), onContextMenu, onHotkey, onWindowState,
// onWindowClosed, onOpenUrl, onOpenFiles, onMediaKey, onNotificationClick,
// onNotificationAction, onUpdateAvailable, onClipboardChange, onLocale,
// onAudioTap, onNavigate, onDownload, onWindowOpen — except
// onSystem(kind, value, app)

await tiny.api.call('method', { params });    // -> backend api.<method>
const off = tiny.api.on('event', fn);         // <- app.push; returns unsubscribe
audio.src = tiny.fileURL(path);   // ALWAYS this, never 'file://' + path
                                  // (breaks on Windows drive letters)
const r = await tiny.fetch(url, opts);        // backend-proxied, no CORS/CSP
tiny.win.open('settings', { page: 'settings.html', size: '420x300',
                            chrome: { frame: false } });
// chrome/x/y/minSize in open() (or tinyjs.json "chrome" for main) apply
// BEFORE first paint — a late setChrome flashes the default window.