@foldspace_npm/harness 0.1.24 → 0.1.25

package/CLAUDE.md

@@ -78,9 +78,11 @@ current CLI contract — risk, prerequisites, effects, next step.
    one that creates data - say so instead.
 
 **Say when the test window is yours, and when it is theirs - on the page and
-in chat.** You and the human share one Chrome window. Before you start looking
-at the app or testing in it, run `npx foldspace badge working` (a bar across
-the top of the window says Foldspace is building here, leave it alone) and say
+in chat.** You and the human share one Chrome window. `observe` and `ask`
+raise the working pill by themselves for as long as they run, and drop it
+after. For the longer stretch - from the moment you start working on their
+window until it is their turn - run `npx foldspace badge working` (the pill at
+the foot of the window says Foldspace is building here, leave it alone) and say
 so in chat: *"I'm going to work in that Chrome window for a few minutes -
 please leave it alone until I tell you it's ready."* When it is their turn,
 `npx foldspace badge ready` takes the pill away (the small corner tag comes
@@ -487,10 +489,15 @@ Each of these cost a real build.
 - **A card matches the panel, not the page.** The card sits in the agent's
   panel - white by default (the agent's theme: `backgroundColor #FFFFFF`,
   `primaryColor` for accents; a `darkTheme` when the panel is dark, and the
-  panel follows the OS colour scheme, not the app's own toggle). `observe
-  styles` samples the page: a dark app gives a dark card in a white panel
-  (seen 2026-09-22). Start from the recipe palettes, put the agent's
-  `primaryColor` in `accent`, and take only font and radius from the page.
+  panel follows the OS colour scheme, not the app's own toggle). **Before the
+  first card, make the brand reference:** `npx foldspace observe styles
+  --write` samples the app's own accent, text, border, font and radius and
+  writes `agent/views/brand.ts` for the panel's white surface - every card
+  imports it, and the recipes' `brand.ts` files are placeholders for it. A
+  dark app keeps its accent and font; its light-on-dark text would vanish on
+  white, so that falls back to greys and the file says so. Record where the
+  values came from in the profile's Brand section. Never copy colours by eye
+  (seen 2026-09-22: a dark card in a white panel).
 - **Plain hex or rgba only.** The panel saves every card to the conversation
   history as an image drawn with html2canvas, which cannot read `oklch()`,
   `lab()` or `color-mix()`: one such value and the saved card is blank

package/bin/ask.mjs

@@ -27,6 +27,7 @@ import {
 import { ATTACH_DAEMON_LOG_FILE } from "../src/attach-daemon.mjs";
 import { CdpPage, parseArgs, printJson, sleep } from "../src/cdp-client.mjs";
 import { recordEvent } from "../src/session-events.mjs";
+import { withWorkingBadge } from "../src/badge-auto.mjs";
 import { resolveProjectDir } from "../src/upgrade.mjs";
 
 const PANEL_ID = "eucera-agent-iframe";
@@ -300,11 +301,15 @@ async function main() {
 
   let attempts = 0;
   let turn;
-  do {
-    if (attempts > 0) await sleep(everyS * 1000);
-    turn = await askOnce();
-    attempts += 1;
-  } while (turn.sent && shouldRetry({ ...turn, attempts, retries }));
+  // The working pill is up while the question is typed and answered - the
+  // human must not type into the same composer - and down before the pictures.
+  await withWorkingBadge(page, async () => {
+    do {
+      if (attempts > 0) await sleep(everyS * 1000);
+      turn = await askOnce();
+      attempts += 1;
+    } while (turn.sent && shouldRetry({ ...turn, attempts, retries }));
+  });
 
   if (!turn.sent) {
     finish({ ok: false, question, reason: "Could not type into the composer.", attempts, url }, 1);

package/bin/observe.mjs

@@ -23,6 +23,7 @@ import path from "node:path";
 
 import { CdpPage, parseArgs, printJson, readLaunchState, sleep } from "../src/cdp-client.mjs";
 import { withoutStealingFocus } from "../src/keep-focus.mjs";
+import { withWorkingBadge } from "../src/badge-auto.mjs";
 import {
   NAV_ITEM_SELECTOR,
   NAV_SCOPE_SELECTOR,
@@ -41,6 +42,7 @@ import {
   rankCandidates,
   readHint,
   refuseWriteFlags,
+  brandFile,
   gotoDestination,
   pageCoverage,
   uncoveredSiblings,
@@ -56,7 +58,7 @@ const SUBCOMMANDS = {
   screen: { values: ["click", "goto", "match", "wait"], flags: [] },
   read: { values: [], flags: [] },
   auth: { values: ["wait"], flags: [] },
-  styles: { values: [], flags: [] },
+  styles: { values: [], flags: ["write"] },
   screenshot: { values: ["out"], flags: [] },
   "wait-login": { values: ["timeout"], flags: [] },
 };
@@ -591,7 +593,7 @@ function lowerKeys(wire = {}, pageSet = {}) {
   return Object.fromEntries(Object.entries(wire).filter(([name]) => !known.has(name.toLowerCase())));
 }
 
-async function runStyles(page) {
+async function runStyles(page, flags = {}) {
   const raw = await page.evaluate(`
     ${VISIBLE_JS}
     const clear = (color) =>
@@ -687,7 +689,7 @@ async function runStyles(page) {
       radius: top(radii)[0] || null,
     };`);
   const { button } = raw;
-  return {
+  const report = {
     ok: true,
     url: printableUrl(raw.url),
     sampledFrom: "computed styles of visible elements",
@@ -709,6 +711,15 @@ async function runStyles(page) {
     boxRadius: raw.radius,
     body: { ...raw.body, color: toHex(raw.body.color) },
   };
+  if (!flags.write) return report;
+  // The brand reference every card imports. Written, not printed: values
+  // copied by hand drift, and re-sampling must be one command.
+  const target = path.join(projectDir, "agent", "views", "brand.ts");
+  const existed = fs.existsSync(target);
+  const { content, notes } = brandFile(report, { url: report.url, date: new Date().toISOString().slice(0, 10) });
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content, "utf8");
+  return { ...report, wrote: path.relative(projectDir, target), replaced: existed, notes };
 }
 
 async function runScreenshot(page, flags) {
@@ -796,11 +807,14 @@ async function main() {
 
   const page = await CdpPage.open({ projectDir });
   try {
-    if (sub === "menu") return await runMenu(page);
-    if (sub === "screen") return await runScreen(page, flags);
-    if (sub === "read") return await runRead(page, flags, rest);
-    if (sub === "auth") return await runAuth(page, flags);
-    if (sub === "styles") return await runStyles(page);
+    // The working pill goes up while the harness drives the human's window,
+    // and comes down after - nobody has to remember it. Not for screenshot:
+    // the picture is for the human, and the pill would be in it.
+    if (sub === "menu") return await withWorkingBadge(page, () => runMenu(page));
+    if (sub === "screen") return await withWorkingBadge(page, () => runScreen(page, flags));
+    if (sub === "read") return await withWorkingBadge(page, () => runRead(page, flags, rest));
+    if (sub === "auth") return await withWorkingBadge(page, () => runAuth(page, flags));
+    if (sub === "styles") return await withWorkingBadge(page, () => runStyles(page, flags));
     return await runScreenshot(page, flags);
   } finally {
     page.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/src/badge-auto.mjs

@@ -0,0 +1,42 @@
+// The working pill, raised by the harness itself while it drives the shared
+// window. `foldspace badge working` exists so the human knows when to leave the
+// window alone - and across a long session of observe and ask it was never
+// set, so both drove the same window (raised by the human, 2026-09-29). The
+// commands know when they are about to drive it, so they raise the pill for
+// as long as they run and put back whatever was there. A pill the agent set
+// on purpose is left alone.
+
+export const BADGE_KEY = "__foldspace_badge__";
+
+export async function readBadge(page) {
+  try {
+    const raw = await page.evaluate(`return sessionStorage.getItem(${JSON.stringify(BADGE_KEY)});`);
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeBadge(page, payload) {
+  await page.evaluate(
+    `sessionStorage.setItem(${JSON.stringify(BADGE_KEY)}, ${JSON.stringify(JSON.stringify(payload))}); return true;`,
+  );
+}
+
+/** Run `action` with the working pill up, then restore what was there before. */
+export async function withWorkingBadge(page, action) {
+  const before = await readBadge(page);
+  if (before?.state === "working") return action(); // set on purpose: theirs to drop
+  let raised = false;
+  try {
+    await writeBadge(page, { state: "working", auto: true });
+    raised = true;
+  } catch {
+    // no badge script on this page (attach not running): nothing to raise
+  }
+  try {
+    return await action();
+  } finally {
+    if (raised) await writeBadge(page, before ?? { state: "label" }).catch(() => {});
+  }
+}

package/src/cli-registry.mjs

@@ -306,10 +306,11 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     options: [
       value("--click", "label", "screen: reach the screen by a navigation label, as a person would"),
-      value("--goto", "path", "screen: a same-origin path"),
+      value("--goto", "path", "screen: a path on this host, or a full https address on a host this project names"),
       value("--match", "words", "screen: rank the requests seen by these words"),
       value("--wait", "ms", "screen/auth: how long to keep listening"),
       value("--out", "file", "screenshot: where to save the PNG"),
+      flag("--write", "styles: write agent/views/brand.ts - the brand reference every card imports"),
       value("--timeout", "seconds", "wait-login: give up after this long", { default: "600" }),
     ],
     prerequisites: ["foldspace inject has opened the test window"],
@@ -317,6 +318,7 @@ export const CLI_COMMANDS = Object.freeze([
       "GET only. Never submits a form; clicks navigation elements only",
       "Prints names, shapes and counts - never values, tokens or cookies",
       "Works while foldspace attach is running",
+      "Raises the working pill on the window while it runs (not for screenshot), and drops it after",
     ],
     next: ["Record what you established in docs/app-profile.md", "Write the handler"],
   }),

package/src/observe-core.mjs

@@ -705,8 +705,46 @@ export function looksLoggedIn({ url, hasPasswordField = false, hosts = [] }) {
 // ---------------------------------------------------------------- styles
 
 /** Computed colours come back as rgb()/rgba(); anything else passes through. */
+// oklch / oklab, as modern apps write their palettes and as Chrome reports
+// them back, converted to sRGB. Cards must be plain hex: the panel saves them
+// to history as an image drawn by a library that cannot read these.
+function okToHex(text) {
+  const match = /^(oklch|oklab)\(\s*([\d.]+%?)\s+(-?[\d.]+%?)\s+(-?[\d.]+)(?:deg)?\s*(?:\/\s*([\d.]+%?))?\s*\)$/i.exec(text);
+  if (!match) return null;
+  const number = (value, scale = 1) => (value.endsWith("%") ? (Number(value.slice(0, -1)) / 100) * scale : Number(value));
+  const L = number(match[2]);
+  let a;
+  let b;
+  if (match[1].toLowerCase() === "oklch") {
+    const C = number(match[3], 0.4);
+    const H = (Number(match[4]) * Math.PI) / 180;
+    a = C * Math.cos(H);
+    b = C * Math.sin(H);
+  } else {
+    a = number(match[3], 0.4);
+    b = number(match[4], 0.4);
+  }
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  const linear = [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+  const channel = (c) => {
+    const v = c <= 0.0031308 ? 12.92 * c : 1.055 * Math.max(c, 0) ** (1 / 2.4) - 0.055;
+    return Math.max(0, Math.min(255, Math.round(v * 255))).toString(16).padStart(2, "0");
+  };
+  const hex = `#${linear.map(channel).join("")}`;
+  const alpha = match[5] === undefined ? 1 : number(match[5]);
+  return alpha >= 1 ? hex : `${hex}${Math.round(alpha * 255).toString(16).padStart(2, "0")}`;
+}
+
 export function toHex(cssColor) {
   const text = String(cssColor || "").trim();
+  const ok = okToHex(text);
+  if (ok) return ok;
   const match = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/i.exec(text);
   if (!match) return text || null;
   const channel = (value) =>
@@ -720,3 +758,69 @@ export function toHex(cssColor) {
   const hex = `#${channel(match[1])}${channel(match[2])}${channel(match[3])}`;
   return alpha >= 1 ? hex : `${hex}${channel(alpha * 255)}`;
 }
+
+// ------------------------------------------------------------ brand file
+
+function luminance(hex) {
+  const m = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})/i.exec(String(hex || ""));
+  if (!m) return null;
+  const [r, g, b] = [m[1], m[2], m[3]].map((part) => parseInt(part, 16) / 255);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+const isHex = (value) => /^#[0-9a-f]{6}([0-9a-f]{2})?$/i.test(String(value || ""));
+
+/**
+ * `agent/views/brand.ts` from what `observe styles` sampled: the app's own
+ * accent, text, border, font and radius, on the panel's white surface. A dark
+ * app keeps its accent, font and radius; its light-on-dark text and borders
+ * would vanish on white, so those fall back to neutral greys and say so.
+ */
+export function brandFile(styles, { url, date, agentPrimary } = {}) {
+  const notes = [];
+  const pick = (value, fallback, name) => {
+    const hex = value ? toHex(value) : null; // rgb / oklch / oklab -> hex; anything else stays as it was
+    if (isHex(hex)) return hex.slice(0, 7).toUpperCase();
+    if (value) notes.push(`${name}: sampled "${value}" is not a plain colour - using ${fallback}`);
+    return fallback;
+  };
+  const background = pick(styles.background, "#FFFFFF", "background");
+  const darkApp = (luminance(background) ?? 1) < 0.4;
+  if (darkApp) notes.push(`the app is dark (${background}); cards sit in the white panel, so text, muted and border are neutral greys`);
+  const text = darkApp ? "#111827" : pick(styles.text, "#111827", "text");
+  const muted = darkApp ? "#6B7280" : pick(styles.textMuted, "#6B7280", "textMuted");
+  const border = darkApp ? "#E5E7EB" : pick(styles.border, "#E5E7EB", "border");
+  const buttonBackground = styles.primaryButton?.background;
+  const accent = isHex(agentPrimary)
+    ? agentPrimary.slice(0, 7).toUpperCase()
+    : pick(buttonBackground || styles.link, "#3248F2", "accent");
+  const accentSource = isHex(agentPrimary) ? "the agent's own primary colour" : buttonBackground ? "the app's primary button" : styles.link ? "the app's links" : "Foldspace blue (nothing sampled)";
+  const accentText = pick(styles.primaryButton?.color, (luminance(accent) ?? 0) > 0.6 ? "#111827" : "#FFFFFF", "accentText");
+  const font = String(styles.fontFamily || "").replace(/["'\\]/g, "").trim() || "Roboto, sans-serif";
+  const radius = /^\d+(\.\d+)?px$/.test(String(styles.boxRadius || "")) ? styles.boxRadius : "8px";
+  const stamp = `${url || "the app"}${date ? ` on ${date}` : ""}`;
+  const lines = [
+    `// Brand reference for this product's cards. Sampled from ${stamp} with`,
+    "// `foldspace observe styles --write`. Cards live in the agent's panel, which is",
+    "// white, so the surface is the panel's; accent, text, border, font and radius",
+    "// are the app's own. Re-run the command to re-sample; do not edit by eye.",
+    "// Plain hex only: the panel saves cards to history as an image drawn by a",
+    "// library that cannot read oklch()/lab().",
+    `// accent: ${accentSource}.`,
+    ...notes.map((note) => `// NOTE ${note}.`),
+    "",
+    "export const brand = {",
+    `  surface: "#FFFFFF",`,
+    `  surface2: "#F5F6FA",`,
+    `  text: "${text}",`,
+    `  muted: "${muted}",`,
+    `  border: "${border}",`,
+    `  accent: "${accent}",`,
+    `  accentText: "${accentText}",`,
+    `  font: '${font}',`,
+    `  radius: "${radius}",`,
+    "} as const;",
+    "",
+  ];
+  return { content: lines.join("\n"), notes, values: { text, muted, border, accent, accentText, font, radius } };
+}

package/src/upgrade.mjs

@@ -307,7 +307,12 @@ export function checkForUpdate(projectDir, options = {}) {
   } else if (skipped) {
     status = "check_skipped";
   } else {
-    const cached = options.cache === false ? null : readCache(projectDir, now);
+    // `fresh` asks the registry whatever was remembered, and still writes the
+    // new answer down. `foldspace upgrade` is always fresh: someone asking to
+    // upgrade minutes after a release was told the previous version was the
+    // latest, for up to 12 hours (seen 2026-09-28).
+    const cached =
+      options.cache === false || options.fresh === true ? null : readCache(projectDir, now);
     const cachedDeprecation =
       cached?.deprecation?.version === running ? cached.deprecation : null;
     if (cached?.latest && cachedDeprecation) {
@@ -445,7 +450,7 @@ export async function runUpgrade(argv, options = {}) {
     );
   }
 
-  const report = checkForUpdate(projectDir, options);
+  const report = checkForUpdate(projectDir, { ...options, fresh: options.fresh ?? true });
 
   if (parsed.checkOnly || (!parsed.yes && !isInteractive(options) && !parsed.refreshInstructions)) {
     return report;