tranquil
Docs

ADR-0016: Business mockups become a served app template

Status: Active · Date: 2026-07-24

References

Context

main-view.html (a list + editor “record” view) and properties.html (a properties/relationships detail panel) lived inside tranquil-automations at mockups/, loaded as file:// URLs and auto-opened on startup by host wiring (lib/mockups.js opened them into the center + right dock and drove live theme sync; lib/mockup-controls.js registered URL-matched pane controls; activation trusted the mockups/ dir over tranquil-rpc). Because apm bundles a package’s whole directory, these pages shipped implicitly in every automations release.

That coupling is wrong for what these pages actually are: not automations chrome, but the seed pattern for future Tranquil “apps” — CRUD or otherwise — that drive automations and operations. They should be a thing you build from, developed and served on their own, not static file:// fixtures baked into an unrelated package and force-opened at launch.

Decision

Extract the two pages (plus mockup.css + fonts/) into a standalone tranquil-app-template repo, serve them over http with live reload via browser-sync run under Deno, and open them into Tranquil’s center + right panes with a small automation shipped in the template. Remove the mockup machinery from tranquil-automations entirely.

  • Serving. deno task dev runs npm:browser-sync to serve app/ on http://localhost:3000 with live reload. Deno executes the npm CLI directly via its npm: compatibility specifier — no package.json, no node_modules checked in; deno.lock is the only committed lockfile.
  • Opening. automations/open-app.js — a tranquil-automations script, not a Deno script — runs in Tranquil’s renderer sandbox (which injects the atom global) and calls atom.workspace.open to put main-view.html in the center and properties.html in the right dock (hideURLBar, allowedLocations/defaultLocation), setting data-theme once to match the current UI theme.
  • Removal. Delete mockups/, lib/mockups.js, lib/mockup-controls.js, the showBusinessMockups config, the auto-open/trust/theme-watch block, and the isMockupUrl exclusion clause in pane-controls-capability.js.

Options considered

  • Standalone served repo + opener automation (chosen) — the template is developed and served on its own; nothing mockup-related ships or auto-opens in tranquil-automations. Fits the “app you build from” intent and the automations-and-operations framing. Cost: a new repo and a running dev server to see the pages.
  • Keep the files in tranquil-automations, just repoint the loader — rejected: leaves the pages shipping in the automations release and keeps the host loader (file:// + theme-watch + trust) that we want gone. Doesn’t make them a template.
  • A dedicated “Open App Template” command in tranquil-automations — rejected: pushes template-specific knowledge back into the client. The opener belongs with the template (as an automation) so a new app carries its own open logic.
  • A Deno-native static server (jsr:@std/http/file-server) — rejected as the default: no live reload. Kept only as a documented fallback if browser-sync ever misbehaves under Deno (it doesn’t today).

Consequences

  • tranquil-automations no longer ships or force-opens the mockups. No pages appear on startup; the package is one feature lighter. The registerDefaultRemoteControls predicate simplifies to “has a webview and is not trusted” — which now also covers the served http://localhost:3000 pages, so they get the standard URL-bar toggle control for free (and hideURLBar keeps them chrome-less). No tranquil-rpc trust is needed anymore.
  • Live authoring. Editing anything under app/ hot-reloads the open panes — a real edit loop the old static file:// pages never had.
  • One removal subtlety worth remembering. pane-controls-capability.js imported isMockupUrl from the deleted mockups.js; a “just delete the files” pass would have left a dangling require that crashes activation and silently drops all automations commands. The import + its predicate clause had to go together.
  • A stale doc. Business Themes & Mockups still describes the pages as tranquil-automations file:// fixtures — it needs an update to point at the new repo/served model (tracked in the delivery notes).
  • browser-sync-under-Deno gotchas are now load-bearing (all in the notes): omit the hoisted node-modules linker in a package.json-free repo, and browser-sync only injects its reload snippet when the request sends Accept: text/html (real browsers always do).
  • Re-evaluate if apps outgrow a single static-server-per-repo (e.g. they need a real build step or a shared component library), at which point the template graduates from “copy this folder” to a scaffolded package.