driggsby 0.2.1 → 0.2.3

package/dist/deploy/deploy-command.js

@@ -36,6 +36,7 @@ export async function runDeploy(options, environment = defaultCredentialEnvironm
         const startedAt = io.now();
         const { outcome, createdApp } = await deployProjectFiles({ baseUrl: session.baseUrl, token: session.token }, projectDirectory, config.slug, collected, {
             live: !options.preview,
+            ...(config.background !== null ? { background: config.background } : {}),
             // The assigned slug is server text, so it prints quoted and
             // length-bounded like every other string this CLI did not author.
             // A validated slug tops out at 63 characters, so the line never

package/dist/dev/dev-command.js

@@ -52,6 +52,7 @@ export async function runDev(options = {}, environment = defaultCredentialEnviro
     try {
         servers = await startDevServers({
             slug: config.slug,
+            background: config.background,
             serveDirectory: config.serveDirectory,
             sdkBundle,
             runToolCall: (tool, argumentsObject) => broker.runToolCall(tool, argumentsObject),

package/dist/dev/dev-servers.js

@@ -117,7 +117,7 @@ async function handleHostRequest(options, hostPort, appOrigin, sseClients, reque
     }
     const path = requestPath(request);
     if (request.method === "GET" && path === "/") {
-        sendHostPage(response, hostPageHtml(options.slug, appOrigin), appOrigin);
+        sendHostPage(response, hostPageHtml(options.slug, appOrigin, options.background), appOrigin);
         return;
     }
     if (request.method === "GET" && path === "/host.js") {

package/dist/dev/host-page.js

@@ -8,12 +8,14 @@
 // The page's script is served as its own file so the page can carry a
 // Content-Security-Policy with no inline scripts.
 //
-// Both interpolations below are HTML-safe by construction, not by escaping:
+// All interpolations below are HTML-safe by construction, not by escaping:
 // `slug` has passed readProjectConfig's strict slug rules (lowercase
-// alphanumerics and dashes only) before runDev ever calls this, and
+// alphanumerics and dashes only) before runDev ever calls this,
 // `appOrigin` is built by startDevServers from a literal plus a bound port
-// number. Anything looser than those two sources must not be passed here.
-export function hostPageHtml(slug, appOrigin) {
+// number, and `background` has passed readProjectConfig's strict hex-color
+// rule (or is null). Anything looser than those sources must not be
+// passed here.
+export function hostPageHtml(slug, appOrigin, background) {
     return `<!doctype html>
 <html lang="en" data-app-origin="${appOrigin}">
 <head>
@@ -45,6 +47,9 @@ export function hostPageHtml(slug, appOrigin) {
       flex: 1;
       width: 100%;
       border: none;
+      /* The app's declared background from driggsby.json, painted while
+         the app loads — the same surface the production host shows. */
+      background: ${background ?? "#ffffff"};
     }
   </style>
 </head>
@@ -66,6 +71,47 @@ export const HOST_PAGE_JS = [
     "const APP_ORIGIN = document.documentElement.dataset.appOrigin;",
     'const frame = document.getElementById("app");',
     "",
+    "// The app's in-page location (a URL fragment), mirrored into this",
+    "// page's own URL and handed back in the hello — the same route sync",
+    "// the production host does, same strict shape on both sides.",
+    "const APP_ROUTE_PATTERN = /^#[A-Za-z0-9\\/\\-._]{1,256}$/;",
+    "",
+    "function sanitizeAppRoute(value) {",
+    '  return typeof value === "string" && APP_ROUTE_PATTERN.test(value) ? value : "";',
+    "}",
+    "",
+    "let appRoute = sanitizeAppRoute(window.location.hash);",
+    "",
+    "// URL writes are bounded (leading + one trailing per window) because",
+    "// the frame controls their rate, and each write is guarded: Safari",
+    "// hard-errors on rapid replaceState bursts.",
+    "const ROUTE_WRITE_WINDOW_MS = 1000;",
+    "let routeWriteTimer = null;",
+    "",
+    "function writeRouteToUrl() {",
+    "  if (window.location.hash === appRoute) {",
+    "    return;",
+    "  }",
+    '  const base = window.location.href.split("#")[0];',
+    "  try {",
+    '    history.replaceState(history.state, "", base + appRoute);',
+    "  } catch (error) {",
+    "    // A refused write costs only URL freshness; the next one retries.",
+    "  }",
+    "}",
+    "",
+    "function applyRoute(hash) {",
+    "  appRoute = hash;",
+    "  if (routeWriteTimer !== null) {",
+    "    return;",
+    "  }",
+    "  writeRouteToUrl();",
+    "  routeWriteTimer = setTimeout(() => {",
+    "    routeWriteTimer = null;",
+    "    writeRouteToUrl();",
+    "  }, ROUTE_WRITE_WINDOW_MS);",
+    "}",
+    "",
     "function postToApp(message) {",
     "  if (frame.contentWindow) {",
     "    frame.contentWindow.postMessage(message, APP_ORIGIN);",
@@ -114,7 +160,25 @@ export const HOST_PAGE_JS = [
     "  }",
     "  const data = event.data;",
     '  if (data.type === "ready") {',
-    '    postToApp({ protocol: PROTOCOL, type: "hello" });',
+    "    const hello = { protocol: PROTOCOL, type: \"hello\" };",
+    '    if (appRoute !== "") {',
+    "      hello.route = appRoute;",
+    "    }",
+    "    postToApp(hello);",
+    "    return;",
+    "  }",
+    '  if (data.type === "route") {',
+    '    // A bare "#" is the explicit cleared sentinel: the app is back at',
+    "    // its no-hash location, so the page URL drops its fragment.",
+    '    if (data.hash === "#") {',
+    '      applyRoute("");',
+    "      return;",
+    "    }",
+    "    const hash = sanitizeAppRoute(data.hash);",
+    '    if (hash === "") {',
+    "      return;",
+    "    }",
+    "    applyRoute(hash);",
     "    return;",
     "  }",
     '  if (data.type !== "call") {',

package/dist/init/templates.js

@@ -4,7 +4,10 @@
 // (`driggsby dev` locally, or the Driggsby console after a deploy). The
 // sample values below are invented for the template and match the real
 // tool result shapes only in structure, so the scaffold's render functions
-// work unchanged when live data replaces them.
+// work unchanged when live data replaces them. The HTML ships a skeleton
+// of the final layout so the first paint — in every context, before any
+// script runs — is muted bars that the first render replaces, fading in
+// at the exact same size so nothing shifts.
 export function indexHtml(slug) {
     return `<!doctype html>
 <html lang="en">
@@ -21,12 +24,56 @@ export function indexHtml(slug) {
       <p class="sample-note" id="sample-note" hidden>Sample data — your real
       accounts appear when this app runs inside Driggsby.</p>
     </header>
+    <!-- The bars below are skeleton placeholders. app.js replaces them
+         with data on its first render; edit the render functions there,
+         and keep the four stat bars in step with what renderOverview
+         draws. (The account rows are just a plausible list length —
+         the real count comes from the data.) -->
     <section aria-label="Overview">
-      <div class="stat-grid" id="overview"></div>
+      <div class="stat-grid" id="overview" aria-busy="true">
+        <div class="stat">
+          <div class="skeleton skeleton-label"></div>
+          <div class="skeleton skeleton-value"></div>
+        </div>
+        <div class="stat">
+          <div class="skeleton skeleton-label"></div>
+          <div class="skeleton skeleton-value"></div>
+        </div>
+        <div class="stat">
+          <div class="skeleton skeleton-label"></div>
+          <div class="skeleton skeleton-value"></div>
+        </div>
+        <div class="stat">
+          <div class="skeleton skeleton-label"></div>
+          <div class="skeleton skeleton-value"></div>
+        </div>
+      </div>
     </section>
     <section aria-label="Accounts">
       <h2>Accounts</h2>
-      <div id="accounts"></div>
+      <div id="accounts" aria-busy="true">
+        <div class="account-row">
+          <div class="account-names">
+            <div class="skeleton skeleton-name"></div>
+            <div class="skeleton skeleton-institution"></div>
+          </div>
+          <div class="skeleton skeleton-balance"></div>
+        </div>
+        <div class="account-row">
+          <div class="account-names">
+            <div class="skeleton skeleton-name"></div>
+            <div class="skeleton skeleton-institution"></div>
+          </div>
+          <div class="skeleton skeleton-balance"></div>
+        </div>
+        <div class="account-row">
+          <div class="account-names">
+            <div class="skeleton skeleton-name"></div>
+            <div class="skeleton skeleton-institution"></div>
+          </div>
+          <div class="skeleton skeleton-balance"></div>
+        </div>
+      </div>
     </section>
   </main>
   <script type="module" src="/-/driggsby-sdk.js"></script>
@@ -44,6 +91,27 @@ export const APP_JS = `// Your app's code. Edit anything — driggsby dev reload
 // Each watch is a live subscription: the callback runs with a fresh result
 // whenever your Driggsby data changes. The sample data below matches the
 // real result shapes, so the render functions work unchanged either way.
+//
+// These are the tools an app can watch — read-only, nothing else responds:
+//
+//   get_overview                 money rollups + every linked account
+//   get_history                  balances, holdings, or debts over time
+//                                (history_type is required: "account_balances",
+//                                "investment_holdings", or "liabilities")
+//   list_accounts                current balances per linked account
+//   list_assets_and_liabilities  the full balance sheet, incl. manual items
+//   list_findings                issues Driggsby has flagged
+//   list_investment_holdings     current investment positions
+//   list_outstanding_debts       linked debts with balances and rates
+//   list_recurring_transactions  subscriptions, bills, and paychecks
+//   query_cash_sql               SQL over cash transactions ({ sql: "..." })
+//   query_investment_sql         SQL over investment activity ({ sql: "..." })
+//   search_cash_transactions     bank and card transaction search
+//   search_investment_activity   trades, dividends, and transfers
+//
+// Params mirror Driggsby's public MCP tools of the same names, with one
+// simplification: those tools require a "reason" string, but a watch can
+// leave it out — Driggsby fills one in naming the dashboard.
 
 // ---------------------------------------------------------------------------
 // Sample data. Every name and number here is invented. It paints only
@@ -104,6 +172,19 @@ function element(tag, className, text) {
   return node;
 }
 
+// The page ships with a skeleton of this exact layout in its HTML — muted
+// bars where the numbers will be — so the very first paint is already the
+// final shape. The first render into a container replaces its skeleton and
+// fades in, so data arriving reads as the page settling, never as content
+// popping. classList.add is idempotent and re-adding a class never restarts
+// its animation, so later live updates repaint in place without re-fading.
+// aria-busy ships in the HTML so assistive tech hears "loading" until the
+// first real content lands.
+function revealOnce(container) {
+  container.classList.add("fade-in");
+  container.removeAttribute("aria-busy");
+}
+
 function renderOverview(result) {
   const rollups = (result && result.summary_rollups) || {};
   const container = document.getElementById("overview");
@@ -122,6 +203,7 @@ function renderOverview(result) {
     );
     container.append(stat);
   }
+  revealOnce(container);
 }
 
 function renderAccounts(result) {
@@ -143,32 +225,32 @@ function renderAccounts(result) {
     row.append(names, element("div", "account-balance", formatMoney(account.current_balance)));
     container.append(row);
   }
+  revealOnce(container);
 }
 
 // ---------------------------------------------------------------------------
 // Live data. window.driggsby exists when the Driggsby SDK loaded — inside
 // Driggsby, or under driggsby dev. Whether anything embeds this page is
 // knowable synchronously: opened directly in a tab, no host will ever
-// answer, so the sample data paints right away and the note explaining it
-// is revealed (it ships hidden in the HTML, so an embedded page never
-// shows it, not even for the moment before this script runs). Embedded,
-// sample numbers never paint at all — a muted loading line holds the
-// accounts area until real data arrives.
+// answer, so the sample data replaces the skeleton right away and the note
+// explaining it is revealed (it ships hidden in the HTML, so an embedded
+// page never shows it, not even for the moment before this script runs).
+// Embedded, sample numbers never paint at all — the shipped skeleton holds
+// the layout until the first real results replace it and fade in.
 // ---------------------------------------------------------------------------
 
 const standalone = window.parent === window;
 const note = document.getElementById("sample-note");
 
 if (standalone) {
+  // The note and the sample values paint together (this whole branch is
+  // one synchronous task). The reveal is kept first so an edit that ever
+  // makes rendering async can't paint values before their label.
+  if (note) note.hidden = false;
   renderOverview(SAMPLE_OVERVIEW);
   renderAccounts(SAMPLE_ACCOUNTS);
-  if (note) note.hidden = false;
-} else {
-  if (note) note.remove();
-  const accounts = document.getElementById("accounts");
-  if (accounts) {
-    accounts.replaceChildren(element("div", "loading-note", "Loading your accounts…"));
-  }
+} else if (note) {
+  note.remove();
 }
 
 if (window.driggsby) {
@@ -235,10 +317,64 @@ h2 {
   display: none;
 }
 
-.loading-note {
-  margin-top: 8px;
-  color: var(--text-muted);
-  font-size: 13px;
+/* The skeleton ships in the HTML so the first paint is the final layout as
+   muted bars; the first render replaces it and fades in (see app.js). The
+   bar margins make each skeleton block exactly the height of the text it
+   stands in for, so nothing shifts when data lands. */
+.skeleton {
+  border-radius: 4px;
+  background: var(--hairline);
+  animation: skeleton-pulse 1.6s ease-in-out infinite;
+}
+
+.skeleton-label {
+  width: 64px;
+  height: 12px;
+  margin: 3.75px 0 0;
+}
+
+.skeleton-value {
+  width: 96px;
+  height: 20px;
+  margin: 8.75px 0 5px;
+}
+
+.skeleton-name {
+  width: 150px;
+  height: 14px;
+  margin: 4px 0 8px;
+}
+
+.skeleton-institution {
+  width: 110px;
+  height: 12px;
+  margin: 4px 0;
+}
+
+.skeleton-balance {
+  width: 72px;
+  height: 14px;
+}
+
+@keyframes skeleton-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.55; }
+}
+
+.fade-in {
+  animation: fade-in 200ms ease-out;
+}
+
+@keyframes fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton,
+  .fade-in {
+    animation: none;
+  }
 }
 
 .stat-grid {
@@ -281,6 +417,10 @@ h2 {
   font-variant-numeric: tabular-nums;
 }
 `;
+// "background" is the template's own page background (styles.css
+// --background): Driggsby paints it while the app loads, so the loading
+// surface matches the app from the first frame. An agent that re-themes
+// the app should keep this equal to the page's real background color.
 export function driggsbyJsonText(slug) {
-    return `{\n  "slug": ${JSON.stringify(slug)},\n  "serve": "."\n}\n`;
+    return `{\n  "slug": ${JSON.stringify(slug)},\n  "serve": ".",\n  "background": "#ffffff"\n}\n`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driggsby",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Set up and build on Driggsby, the MCP server for personal finance.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@driggsby/deploy": "0.2.1",
-    "@driggsby/sdk": "0.2.1"
+    "@driggsby/deploy": "0.2.3",
+    "@driggsby/sdk": "0.2.3"
   }
 }