driggsby 0.2.2 → 0.2.4

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,108 @@ 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 because the frame controls their rate, but",
+    "// ordinary clicking should not feel the bound — a token bucket does",
+    "// both, matching the production host: a flurry of up to 15",
+    "// navigations writes instantly, sustained clicking faster than one",
+    "// per 600ms then paces at 600ms, and a frame spamming routes drains",
+    "// the bucket and degrades to paced trailing writes that still land",
+    "// the final state. Burst (15) plus refills (one per 600ms = 50 per",
+    "// 30s) tops out at 65 writes per 30s, leaving at least ~35 of",
+    "// Safari's ~100-per-30s per-document replaceState budget for the",
+    "// host page's own writes. Keep these two constants identical to the",
+    "// production host's; nothing pins them across the two codebases.",
+    "const ROUTE_WRITE_BUCKET_CAPACITY = 15;",
+    "const ROUTE_WRITE_REFILL_MS = 600;",
+    "let routeTokens = ROUTE_WRITE_BUCKET_CAPACITY;",
+    "let routeLastRefillMs = Date.now();",
+    "let routeWriteTimer = null;",
+    "",
+    "function refillRouteTokens() {",
+    "  const now = Date.now();",
+    "  // A backward clock step would otherwise strand the refill mark in",
+    "  // the future and stall every write until the clock caught back up.",
+    "  if (now < routeLastRefillMs) {",
+    "    routeLastRefillMs = now;",
+    "  }",
+    "  const earned = Math.floor((now - routeLastRefillMs) / ROUTE_WRITE_REFILL_MS);",
+    "  if (earned < 1) {",
+    "    return;",
+    "  }",
+    "  routeTokens = Math.min(ROUTE_WRITE_BUCKET_CAPACITY, routeTokens + earned);",
+    "  routeLastRefillMs += earned * ROUTE_WRITE_REFILL_MS;",
+    "}",
+    "",
+    "function takeRouteToken() {",
+    "  refillRouteTokens();",
+    "  if (routeTokens < 1) {",
+    "    return false;",
+    "  }",
+    "  routeTokens -= 1;",
+    "  return true;",
+    "}",
+    "",
+    "function routeRetryDelayMs() {",
+    "  refillRouteTokens();",
+    "  if (routeTokens >= 1) {",
+    "    return 1;",
+    "  }",
+    "  const sinceRefill = Date.now() - routeLastRefillMs;",
+    "  return Math.min(ROUTE_WRITE_REFILL_MS, Math.max(1, ROUTE_WRITE_REFILL_MS - sinceRefill));",
+    "}",
+    "",
+    "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 scheduleTrailingRouteWrite() {",
+    "  routeWriteTimer = setTimeout(() => {",
+    "    routeWriteTimer = null;",
+    "    if (takeRouteToken()) {",
+    "      writeRouteToUrl();",
+    "    } else {",
+    "      // The clock can land a hair before the token accrues; wait out",
+    "      // the remainder rather than writing over budget.",
+    "      scheduleTrailingRouteWrite();",
+    "    }",
+    "  }, routeRetryDelayMs());",
+    "}",
+    "",
+    "function applyRoute(hash) {",
+    "  appRoute = hash;",
+    "  if (routeWriteTimer !== null) {",
+    "    return; // the trailing write reads appRoute",
+    "  }",
+    "  // Already mirrored: nothing to write, no token spent on nothing.",
+    "  if (window.location.hash === hash) {",
+    "    return;",
+    "  }",
+    "  if (takeRouteToken()) {",
+    "    writeRouteToUrl();",
+    "    return;",
+    "  }",
+    "  scheduleTrailingRouteWrite();",
+    "}",
+    "",
     "function postToApp(message) {",
     "  if (frame.contentWindow) {",
     "    frame.contentWindow.postMessage(message, APP_ORIGIN);",
@@ -114,7 +221,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

@@ -91,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
@@ -396,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.2",
+  "version": "0.2.4",
   "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.2",
-    "@driggsby/sdk": "0.2.2"
+    "@driggsby/deploy": "0.2.4",
+    "@driggsby/sdk": "0.2.4"
   }
 }