@notis_ai/cli 0.2.0-beta.178.1 → 0.2.0-beta.181.1

package/dist/agent-hooks/notis-agent-hook.mjs

@@ -11748,7 +11748,79 @@ async function startAppTestServer({ apps, port, harness = {} }) {
 import { spawn as spawn2, spawnSync } from "node:child_process";
 import { mkdirSync as mkdirSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname as dirname5 } from "node:path";
-var PREPARE_CAPTURE_SCRIPT = "(() => { const s = document.getElementById('harness-status'); if (s) s.style.display = 'none'; const r = document.getElementById('root'); if (r) { r.style.paddingTop = '0'; r.style.minHeight = '0'; } document.body.style.minHeight = '0'; document.documentElement.style.minHeight = '0'; return true; })()";
+
+// src/runtime/screenshot-framing.js
+function measureScreenshotContent() {
+  const root = document.getElementById("root");
+  if (!root) return null;
+  const viewportWidth = document.documentElement.clientWidth;
+  const visible = (element) => {
+    const rect2 = element.getBoundingClientRect();
+    const style = getComputedStyle(element);
+    return rect2.width > 0 && rect2.height > 0 && style.display !== "none" && style.visibility !== "hidden";
+  };
+  let node = root;
+  let content = null;
+  while (node) {
+    const hasOwnText = Array.from(node.childNodes).some(
+      (child) => child.nodeType === 3 && child.textContent.trim()
+    );
+    const children = Array.from(node.children).filter(visible);
+    if (hasOwnText || children.length !== 1) break;
+    node = children[0];
+    const rect2 = node.getBoundingClientRect();
+    if (["DIV", "MAIN", "SECTION", "ARTICLE", "FORM"].includes(node.tagName) && rect2.width >= 320 && rect2.height >= 160 && rect2.width < viewportWidth * 0.9) {
+      content = node;
+    }
+  }
+  if (!content) return null;
+  content.setAttribute("data-notis-screenshot-content", "");
+  const rect = content.getBoundingClientRect();
+  return {
+    selector: "[data-notis-screenshot-content]",
+    width: rect.width,
+    height: rect.height,
+    viewport_width: viewportWidth
+  };
+}
+var MEASURE_SCREENSHOT_CONTENT_SCRIPT = `(${measureScreenshotContent.toString()})()`;
+function contentCapturePlan(bounds, viewport, outputWidth, outputHeight) {
+  const aspect = outputWidth / outputHeight;
+  if (bounds.width / bounds.height < aspect * 0.75) {
+    const width = Math.max(768, Math.ceil((bounds.width + 32) / 8) * 8);
+    return { focus: false, width, height: Math.round(width / aspect), scale: outputWidth / width };
+  }
+  return {
+    focus: true,
+    width: viewport.width,
+    height: viewport.height,
+    scale: Math.min(4, outputWidth / bounds.width)
+  };
+}
+function safeViewportHeight(rectangles, height) {
+  const crossing = rectangles.filter((rect) => rect.top < height && rect.bottom > height && rect.top >= height * 0.85);
+  return crossing.length ? Math.max(Math.ceil(height * 0.85), Math.floor(Math.min(...crossing.map((rect) => rect.top)) - 8)) : height;
+}
+var SAFE_VIEWPORT_HEIGHT_SCRIPT = `(() => {
+  const root = document.getElementById('root');
+  if (!root) return innerHeight;
+  const rects = [];
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let node;
+  while ((node = walker.nextNode())) {
+    if (!node.textContent.trim() || getComputedStyle(node.parentElement).visibility !== 'visible') continue;
+    const range = document.createRange(); range.selectNodeContents(node);
+    for (const rect of range.getClientRects()) rects.push({ top: rect.top, bottom: rect.bottom });
+  }
+  for (const control of root.querySelectorAll('button,input,select,textarea')) {
+    const rect = control.getBoundingClientRect();
+    rects.push({ top: rect.top, bottom: rect.bottom });
+  }
+  return (${safeViewportHeight.toString()})(rects, innerHeight);
+})()`;
+
+// src/runtime/agent-browser.js
+var PREPARE_CAPTURE_SCRIPT = "(() => { const r = document.getElementById('root'); if (r) r.style.minHeight = '0'; document.body.style.minHeight = '0'; document.documentElement.style.minHeight = '0'; return true; })()";
 var FONTS_STATUS_SCRIPT = "(() => (document.fonts ? document.fonts.status : 'loaded'))()";
 var CONTENT_HEIGHT_SCRIPT = "(() => { const r = document.getElementById('root'); if (!r) return Math.ceil(document.documentElement.scrollHeight); return Math.ceil(Math.max(r.scrollHeight, r.getBoundingClientRect().height)); })()";
 var MIN_CSS_VIEWPORT_HEIGHT = 720;
@@ -12019,6 +12091,7 @@ async function captureHarnessScreenshot({
   sessionName,
   screenshotPath,
   focusSelector = null,
+  frameContent = false,
   width = 2e3,
   height = 1250,
   timeoutMs = 15e3
@@ -12103,12 +12176,49 @@ async function captureHarnessScreenshot({
     }
   }
   await delay(500);
+  let contentBounds = null;
+  if (frameContent && !focusSelector) {
+    const measured = await runAgentBrowser(
+      ["--session", sessionName, "--json", "eval", MEASURE_SCREENSHOT_CONTENT_SCRIPT],
+      { timeoutMs: 5e3 }
+    );
+    if (measured.exitCode === 0) {
+      try {
+        const bounds = parseHarnessFromEval(measured.stdout);
+        if (bounds?.selector === "[data-notis-screenshot-content]" && Number.isFinite(bounds.width) && bounds.width > 0 && Number.isFinite(bounds.height) && bounds.height > 0) {
+          contentBounds = bounds;
+        }
+      } catch {
+      }
+    }
+  }
+  let captureFocus = focusSelector || contentBounds?.selector || null;
+  if (contentBounds && scaledViewport) {
+    const plan = contentCapturePlan(contentBounds, framing || initial, width, height);
+    if (await setViewport(sessionName, plan.width, plan.height, plan.scale)) {
+      await delay(300);
+      if (!plan.focus) {
+        const safeHeight = await evalNumber(sessionName, SAFE_VIEWPORT_HEIGHT_SCRIPT, plan.height);
+        if (safeHeight < plan.height && await setViewport(sessionName, plan.width, safeHeight, plan.scale)) {
+          plan.height = safeHeight;
+        }
+      }
+      captureFocus = plan.focus ? contentBounds.selector : null;
+      framing = {
+        ...framing || {},
+        ...plan,
+        content_bounds: contentBounds,
+        capture_mode: plan.focus ? "content" : "width-fit-viewport"
+      };
+      await delay(300);
+    }
+  }
   const designResult = await evalDesignAssertions(sessionName, { viewport: "capture" });
   const design = Array.isArray(designResult) ? designResult : [];
   mkdirSync3(dirname5(screenshotPath), { recursive: true });
   const screenshotArgs = ["--session", sessionName, "screenshot"];
-  if (focusSelector) {
-    screenshotArgs.push(focusSelector);
+  if (captureFocus) {
+    screenshotArgs.push(captureFocus);
   }
   screenshotArgs.push(screenshotPath, "--screenshot-format", "png");
   const shot = await runAgentBrowser(screenshotArgs, { timeoutMs: 15e3 });
@@ -12116,7 +12226,9 @@ async function captureHarnessScreenshot({
     return { ok: false, mounted: true, screenshotPath: null, errors: lastErrors, timed_out: false, tool_error: commandError("screenshot", shot) };
   }
   const dimensions = pngDimensions2(screenshotPath);
-  if (!focusSelector && framing && (!dimensions || dimensions.width !== width || dimensions.height !== height)) {
+  const expectedDimensions = framing?.capture_mode === "width-fit-viewport" ? { width: Math.round(framing.width * framing.scale), height: Math.round(framing.height * framing.scale) } : { width, height };
+  const tolerance = frameContent ? 1 : 0;
+  if (!captureFocus && framing && (!dimensions || Math.abs(dimensions.width - expectedDimensions.width) > tolerance || Math.abs(dimensions.height - expectedDimensions.height) > tolerance)) {
     await setViewport(sessionName, width, height);
     await delay(300);
     const retry = await runAgentBrowser(
@@ -12128,10 +12240,11 @@ async function captureHarnessScreenshot({
     }
     framing = null;
   }
-  if (focusSelector) {
+  if (captureFocus) {
     framing = {
       ...framing || {},
-      focus_selector: focusSelector,
+      focus_selector: captureFocus,
+      content_bounds: contentBounds,
       source_dimensions: dimensions
     };
   }
@@ -12187,7 +12300,7 @@ var DESIGN_ASSERTIONS_SCRIPT = `(() => {
   };
   const all = Array.from(root.querySelectorAll('*'));
   for (const el of all) {
-    if (el.id === 'harness-status' || !visible(el) || isControl(el)) continue;
+    if (!visible(el) || isControl(el)) continue;
     if (isBox(el)) {
       let p = el.parentElement; let depth = 0;
       while (p && p !== root && depth < 6) { if (!isControl(p) && isBox(p)) { push('nested_border_box', el); break; } p = p.parentElement; depth += 1; }
@@ -12204,7 +12317,7 @@ var DESIGN_ASSERTIONS_SCRIPT = `(() => {
     const text = (node.textContent || '').trim();
     if (!text) continue;
     const el = node.parentElement;
-    if (!el || el.closest('#harness-status') || !visible(el)) continue;
+    if (!el || !visible(el)) continue;
     const size = parseFloat(getComputedStyle(el).fontSize);
     if (size > 0 && size < 12) push('text_below_12px', el, { font_size: size });
     if (/^Loading(\\.{3}|\\u2026)?(\\s|$)/.test(text)) push('loading_placeholder_after_mount', el);
@@ -12322,15 +12435,16 @@ function resolveStoreScreenshotAccent(accent, seed = "notis-app") {
   }
   return ACCENT_NAMES[stableHash(seed) % ACCENT_NAMES.length];
 }
-function storeScreenshotLayout(width = 2e3, height = 1250) {
+function storeScreenshotLayout(width = 2e3, height = 1250, contentAspect = STORE_SCREENSHOT_ASPECT) {
+  const aspect = Number.isFinite(contentAspect) && contentAspect > 0 ? contentAspect : STORE_SCREENSHOT_ASPECT;
   const horizontalInset = Math.max(48, Math.round(width * 0.06));
   const verticalInset = Math.max(40, Math.round(height * 0.06));
   let cardWidth = width - horizontalInset * 2;
-  let cardHeight = Math.round(cardWidth / STORE_SCREENSHOT_ASPECT);
+  let cardHeight = Math.round(cardWidth / aspect);
   const maximumCardHeight = height - verticalInset * 2;
   if (cardHeight > maximumCardHeight) {
     cardHeight = maximumCardHeight;
-    cardWidth = Math.round(cardHeight * STORE_SCREENSHOT_ASPECT);
+    cardWidth = Math.round(cardHeight * aspect);
   }
   const cardLeft = Math.round((width - cardWidth) / 2);
   const cardTop = Math.round((height - cardHeight) / 2) - Math.round(height * 8e-3);
@@ -12366,11 +12480,12 @@ async function composeStoreScreenshot({
 }) {
   const sharp = await loadSharp();
   const resolvedTheme = theme === "dark" ? "dark" : "light";
-  const layout = storeScreenshotLayout(width, height);
+  const source = await sharp(inputPath).metadata();
+  const layout = storeScreenshotLayout(width, height, source.width / source.height);
   const resolvedAccent = resolveStoreScreenshotAccent(accent, seed);
   const roundedCapture = await sharp(inputPath).resize(layout.cardWidth, layout.cardHeight, {
-    fit: "cover",
-    position: focused ? "top" : "centre"
+    fit: "contain",
+    background: resolvedTheme === "dark" ? "#09090b" : "#ffffff"
   }).composite([{
     input: roundedRectSvg(layout.cardWidth, layout.cardHeight, layout.radius),
     blend: "dest-in"
@@ -13776,6 +13891,7 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
         sessionName: captureSessionName,
         screenshotPath: browserScreenshotPath,
         focusSelector: ctx.options.raw ? null : focus,
+        frameContent: !ctx.options.raw,
         width,
         height,
         timeoutMs: Number.parseInt(ctx.globalOptions.timeoutMs || "", 10) || 15e3
@@ -13790,7 +13906,7 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
             height,
             accent: appConfig.accent,
             seed: appConfig.name || manifest.app?.name || appSlug,
-            focused: Boolean(focus),
+            focused: Boolean(result.framing?.focus_selector),
             theme: theme || "light"
           });
         } catch (error) {
@@ -14085,15 +14201,20 @@ async function appsDeployHandler(ctx) {
     } catch {
       warnings.push("The app was updated, but the temporary release directory needs local cleanup.");
     }
+    const skillReviews = (Array.isArray(result.payload.skill_reviews) ? result.payload.skill_reviews : []).filter((review) => review && typeof review.review_url === "string");
     return ctx.output.emitSuccess({
       command: ctx.spec.command_path.join(" "),
       data: {
         app_id: appId,
         version: deployedVersion,
-        idempotency_key: idempotencyKey
+        idempotency_key: idempotencyKey,
+        ...skillReviews.length ? { skill_reviews: skillReviews } : {}
       },
       warnings,
-      humanSummary: `Deployed to app ${appId} (version ${deployedVersion})`,
+      humanSummary: [
+        `Deployed to app ${appId} (version ${deployedVersion})`,
+        ...skillReviews.map((review) => `Review ${review.skill} changes: ${review.review_url}`)
+      ].join("\n"),
       meta: { mutating: true, idempotency_key: idempotencyKey }
     });
   } finally {

package/dist/base-skills/notis-apps/SKILL.md

@@ -46,6 +46,8 @@ For every app UI create/edit task, read both [Design](references/design.md) and
   no-deploy, and explicit-consent requirements. Store publication is separate.
 - Preserve the exact app identity, account/team scope, permissions, and user data.
   Reconcile an uncertain release instead of blindly retrying it.
+- Before Store submission, complete the [publication privacy and portability gate](references/release.md#publication-privacy-and-portability-gate).
+  Public examples must be fictional; never publish the owner's workspace data.
 - Use SDK hooks and declared tools. Let Notis own its sidebar, search, runtime,
   and rendering boundary; do not query host DOM or recreate that chrome in the app.
 

package/dist/base-skills/notis-apps/references/architecture.md

@@ -7,8 +7,11 @@ All Notis apps are built using the Notis CLI, either locally in a repo workspace
 - the portal renders it as a React component inside the portal's React tree
 
 Use standard React pages in `app/`, not Next.js or a custom server. The host
-chooses a trusted shadow root or an isolated Store frame; do not create your own
-iframe, query Portal-owned DOM, or install a window-global runtime. The host owns
+uses one React/Shadow DOM runtime for authored apps, Store installations,
+duplicates and SDK reports. Do not create your own iframe, query Portal-owned
+DOM, or install a window-global runtime. Shadow DOM isolates styles, not
+JavaScript or credentials: loaded bundles share the Portal browser context.
+The host owns
 theme injection and authentication. App code uses SDK hooks and the final tool
 names discovered through the CLI, declared in `notis.config.ts` and enforced by
 the backend. Runtime permissions stay least-authority; releasing an app does not

package/dist/base-skills/notis-apps/references/release.md

@@ -65,6 +65,50 @@ not required for an ordinary Workspace update.
 
 ## Special cases — read only when relevant
 
+### Publication privacy and portability gate
+
+Before submitting or updating a Store listing:
+
+1. Inventory the exact public source archive, listing text/media, database schemas,
+   starter rows, bundled skills (including scripts/references), and automation
+   prompts/configuration. Review their actual contents, not just filenames or
+   a passing secret scan. Exclude personal records, transcripts, health/journal
+   history, customer details, private repository/account identifiers, credentials,
+   local paths, run logs, and private links. Do not merely replace a person's name
+   in otherwise real data. Rebuild examples from wholly fictional scenarios.
+2. Keep live owner databases structure-only (`seedDocuments` absent or false).
+   Opting in seeds the database's live rows, including folders: it is not a
+   fixture selector. Use fictional screenshot fixtures and an explicit, idempotent
+   onboarding demo-data option. If starter rows are needed in the install snapshot,
+   publish only from an isolated, verified fictional dataset; never replace or
+   delete the owner's real data to prepare a submission. When the user asks for
+   examples to come with the app, include them in that verified install snapshot:
+   screenshot fixtures or an optional onboarding seed step do not satisfy this.
+3. Bundle the full dependency closure of every app/automation skill, including
+   referenced helpers and resources. Remove private account-specific defaults;
+   resolve the installer's databases, connections, repository, timezone and
+   delivery choices at runtime. Preserve existing owner's schedules and data.
+4. Declare a source-owned onboarding skill. It must work through available MCP
+   tools or the Notis CLI in any agent harness, without requiring Notis Manager,
+   vendor-specific delegation tools, hidden local files, or publisher access.
+   Discover tools and inspect schemas before calls; reconcile existing resources
+   before creating them. Obtain installer choices before enabling automation or
+   external actions. Installing examples must not activate external deliveries.
+5. Test onboarding as an independent harness-native proof agent using an account
+   isolated from the publisher, then rerun to prove no duplicates. Exercise each
+   route and its interactions with fictional data, including empty/error states.
+   Record exact identities, versions, results and run-created resource cleanup;
+   never use owner records as writable test fixtures.
+   For bundled starter-data claims, install the actual published listing into an
+   empty test account and read back its rows before onboarding or any manual data
+   writes. Confirm the installed listing version and remapped relations; do not
+   substitute an editable-source deployment for this Store-install test.
+6. Inspect the final submitted snapshot and media after packaging. Record the
+   privacy audit and verification against that exact source version. Any unknown
+   provenance, missing dependency, untested onboarding or suspected personal data
+   blocks submission until resolved. Never equate submission with review approval
+   or Store publication.
+
 ### Unreleased container or stale checkout
 
 An unreleased container has no source to pull. Recover its original local source,

package/dist/sdk/src/runtime.ts

@@ -368,6 +368,8 @@ export interface RuntimeResource {
   kind: 'app' | 'report';
   /** Host-provided adoption eligibility, never report-authored authority. */
   analytics_eligible?: boolean;
+  /** Host-derived report family for adoption analytics, e.g. skill review reports. */
+  report_kind?: 'skill_review' | 'custom';
   id: string;
   revision: number;
   name?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.0-beta.178.1",
+  "version": "0.2.0-beta.181.1",
   "description": "Agent-first Notis CLI for apps and generic tool execution",
   "type": "module",
   "bin": {

package/src/command-specs/apps.js

@@ -935,6 +935,7 @@ async function appsScreenshotHandler(ctx) {
         sessionName: captureSessionName,
         screenshotPath: browserScreenshotPath,
         focusSelector: ctx.options.raw ? null : focus,
+        frameContent: !ctx.options.raw,
         width,
         height,
         timeoutMs: Number.parseInt(ctx.globalOptions.timeoutMs || '', 10) || 15_000,
@@ -949,7 +950,7 @@ async function appsScreenshotHandler(ctx) {
             height,
             accent: appConfig.accent,
             seed: appConfig.name || manifest.app?.name || appSlug,
-            focused: Boolean(focus),
+            focused: Boolean(result.framing?.focus_selector),
             theme: theme || 'light',
           });
         } catch (error) {
@@ -1256,15 +1257,22 @@ async function appsDeployHandler(ctx) {
     try { release.close(); }
     catch { warnings.push('The app was updated, but the temporary release directory needs local cleanup.'); }
 
+    // One review report per skill this release changed; share the link when the user should review it.
+    const skillReviews = (Array.isArray(result.payload.skill_reviews) ? result.payload.skill_reviews : [])
+      .filter((review) => review && typeof review.review_url === 'string');
     return ctx.output.emitSuccess({
       command: ctx.spec.command_path.join(' '),
       data: {
         app_id: appId,
         version: deployedVersion,
         idempotency_key: idempotencyKey,
+        ...(skillReviews.length ? { skill_reviews: skillReviews } : {}),
       },
       warnings,
-      humanSummary: `Deployed to app ${appId} (version ${deployedVersion})`,
+      humanSummary: [
+        `Deployed to app ${appId} (version ${deployedVersion})`,
+        ...skillReviews.map((review) => `Review ${review.skill} changes: ${review.review_url}`),
+      ].join('\n'),
       meta: { mutating: true, idempotency_key: idempotencyKey },
     });
   } finally {

package/src/runtime/agent-browser.js

@@ -1,19 +1,15 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-
-export const HIDE_HARNESS_STATUS_SCRIPT =
-  "(() => { const el = document.getElementById('harness-status'); if (el) el.style.opacity = '0'; return true; })()";
+import { contentCapturePlan, MEASURE_SCREENSHOT_CONTENT_SCRIPT, SAFE_VIEWPORT_HEIGHT_SCRIPT } from './screenshot-framing.js';
 
 /**
- * Prepare the mounted harness page for a listing capture: remove the debug
- * banner and the layout the harness adds around the app (top padding for the
- * banner, 100vh min-height) so content height can be measured and framed
- * without artificial whitespace.
+ * Prepare the mounted harness page for a listing capture: remove the 100vh
+ * min-height the harness adds around the app so content height can be
+ * measured and framed without artificial whitespace.
  */
 const PREPARE_CAPTURE_SCRIPT =
-  "(() => { const s = document.getElementById('harness-status'); if (s) s.style.display = 'none';" +
-  " const r = document.getElementById('root'); if (r) { r.style.paddingTop = '0'; r.style.minHeight = '0'; }" +
+  "(() => { const r = document.getElementById('root'); if (r) r.style.minHeight = '0';" +
   " document.body.style.minHeight = '0'; document.documentElement.style.minHeight = '0'; return true; })()";
 
 const FONTS_STATUS_SCRIPT =
@@ -322,18 +318,18 @@ export async function runHarnessRoute({
 
 /**
  * Open a harness route, wait for it to mount, then capture a PNG screenshot of
- * the rendered app. Output is always exactly `width` x `height` physical
- * pixels (default 2000x1250, the 16:10 the listing validator expects), but the
- * CSS viewport is fitted to the rendered content height: short pages render
- * larger (no dead whitespace below the app), tall pages get more room before
- * cropping. The deviceScaleFactor maps the fitted CSS viewport back onto the
- * fixed output frame. Used by `notis apps screenshot`.
+ * the rendered app. Raw captures retain exact requested pixel dimensions.
+ * Framed captures can select the complete bounded app or a width-fitted first
+ * screen; the Store compositor normalizes them to the final listing size.
+ * Device scaling keeps text sharp at that size without changing app styles.
+ * Used by `notis apps screenshot`.
  */
 export async function captureHarnessScreenshot({
   url,
   sessionName,
   screenshotPath,
   focusSelector = null,
+  frameContent = false,
   width = 2000,
   height = 1250,
   timeoutMs = 15_000,
@@ -433,13 +429,50 @@ export async function captureHarnessScreenshot({
 
   // Let the route settle (async data, resize transitions) before the capture.
   await delay(500);
+
+  let contentBounds = null;
+  if (frameContent && !focusSelector) {
+    const measured = await runAgentBrowser(
+      ['--session', sessionName, '--json', 'eval', MEASURE_SCREENSHOT_CONTENT_SCRIPT],
+      { timeoutMs: 5000 },
+    );
+    if (measured.exitCode === 0) {
+      try {
+        const bounds = parseHarnessFromEval(measured.stdout);
+        if (bounds?.selector === '[data-notis-screenshot-content]'
+          && Number.isFinite(bounds.width) && bounds.width > 0
+          && Number.isFinite(bounds.height) && bounds.height > 0) {
+          contentBounds = bounds;
+        }
+      } catch { /* Keep the complete viewport if layout measurement is unavailable. */ }
+    }
+  }
+  let captureFocus = focusSelector || contentBounds?.selector || null;
+  if (contentBounds && scaledViewport) {
+    const plan = contentCapturePlan(contentBounds, framing || initial, width, height);
+    if (await setViewport(sessionName, plan.width, plan.height, plan.scale)) {
+      await delay(300);
+      if (!plan.focus) {
+        const safeHeight = await evalNumber(sessionName, SAFE_VIEWPORT_HEIGHT_SCRIPT, plan.height);
+        if (safeHeight < plan.height && await setViewport(sessionName, plan.width, safeHeight, plan.scale)) {
+          plan.height = safeHeight;
+        }
+      }
+      captureFocus = plan.focus ? contentBounds.selector : null;
+      framing = {
+        ...(framing || {}), ...plan, content_bounds: contentBounds,
+        capture_mode: plan.focus ? 'content' : 'width-fit-viewport',
+      };
+      await delay(300);
+    }
+  }
   const designResult = await evalDesignAssertions(sessionName, { viewport: 'capture' });
   const design = Array.isArray(designResult) ? designResult : [];
 
   mkdirSync(dirname(screenshotPath), { recursive: true });
   const screenshotArgs = ['--session', sessionName, 'screenshot'];
-  if (focusSelector) {
-    screenshotArgs.push(focusSelector);
+  if (captureFocus) {
+    screenshotArgs.push(captureFocus);
   }
   screenshotArgs.push(screenshotPath, '--screenshot-format', 'png');
   const shot = await runAgentBrowser(screenshotArgs, { timeoutMs: 15_000 });
@@ -451,7 +484,13 @@ export async function captureHarnessScreenshot({
   // capture came out wrong (e.g. the browser ignored the scale factor),
   // recapture once at a plain fixed viewport.
   const dimensions = pngDimensions(screenshotPath);
-  if (!focusSelector && framing && (!dimensions || dimensions.width !== width || dimensions.height !== height)) {
+  const expectedDimensions = framing?.capture_mode === 'width-fit-viewport'
+    ? { width: Math.round(framing.width * framing.scale), height: Math.round(framing.height * framing.scale) }
+    : { width, height };
+  // Fractional browser scaling can round one pixel either way. Framed output
+  // is normalized by the compositor; raw captures still require exact pixels.
+  const tolerance = frameContent ? 1 : 0;
+  if (!captureFocus && framing && (!dimensions || Math.abs(dimensions.width - expectedDimensions.width) > tolerance || Math.abs(dimensions.height - expectedDimensions.height) > tolerance)) {
     await setViewport(sessionName, width, height);
     await delay(300);
     const retry = await runAgentBrowser(
@@ -464,10 +503,11 @@ export async function captureHarnessScreenshot({
     framing = null;
   }
 
-  if (focusSelector) {
+  if (captureFocus) {
     framing = {
       ...(framing || {}),
-      focus_selector: focusSelector,
+      focus_selector: captureFocus,
+      content_bounds: contentBounds,
       source_dimensions: dimensions,
     };
   }
@@ -538,7 +578,7 @@ export const DESIGN_ASSERTIONS_SCRIPT = `(() => {
   };
   const all = Array.from(root.querySelectorAll('*'));
   for (const el of all) {
-    if (el.id === 'harness-status' || !visible(el) || isControl(el)) continue;
+    if (!visible(el) || isControl(el)) continue;
     if (isBox(el)) {
       let p = el.parentElement; let depth = 0;
       while (p && p !== root && depth < 6) { if (!isControl(p) && isBox(p)) { push('nested_border_box', el); break; } p = p.parentElement; depth += 1; }
@@ -555,7 +595,7 @@ export const DESIGN_ASSERTIONS_SCRIPT = `(() => {
     const text = (node.textContent || '').trim();
     if (!text) continue;
     const el = node.parentElement;
-    if (!el || el.closest('#harness-status') || !visible(el)) continue;
+    if (!el || !visible(el)) continue;
     const size = parseFloat(getComputedStyle(el).fontSize);
     if (size > 0 && size < 12) push('text_below_12px', el, { font_size: size });
     if (/^Loading(\\.{3}|\\u2026)?(\\s|$)/.test(text)) push('loading_placeholder_after_mount', el);

package/src/runtime/screenshot-framing.js

@@ -0,0 +1,85 @@
+/** Runs only in the capture harness, never in an installed app. */
+export function measureScreenshotContent() {
+  const root = document.getElementById('root');
+  if (!root) return null;
+  const viewportWidth = document.documentElement.clientWidth;
+  const visible = (element) => {
+    const rect = element.getBoundingClientRect();
+    const style = getComputedStyle(element);
+    return rect.width > 0 && rect.height > 0
+      && style.display !== 'none' && style.visibility !== 'hidden';
+  };
+
+  // Follow layout wrappers only while they contain the entire visible app.
+  // Never select one column, card, or control out of a multi-pane layout.
+  let node = root;
+  let content = null;
+  while (node) {
+    const hasOwnText = Array.from(node.childNodes).some(
+      (child) => child.nodeType === 3 && child.textContent.trim(),
+    );
+    const children = Array.from(node.children).filter(visible);
+    if (hasOwnText || children.length !== 1) break;
+    node = children[0];
+    const rect = node.getBoundingClientRect();
+    if (['DIV', 'MAIN', 'SECTION', 'ARTICLE', 'FORM'].includes(node.tagName)
+      && rect.width >= 320 && rect.height >= 160
+      && rect.width < viewportWidth * 0.9) {
+      content = node;
+    }
+  }
+  if (!content) return null;
+  content.setAttribute('data-notis-screenshot-content', '');
+  const rect = content.getBoundingClientRect();
+  return {
+    selector: '[data-notis-screenshot-content]',
+    width: rect.width,
+    height: rect.height,
+    viewport_width: viewportWidth,
+  };
+}
+
+export const MEASURE_SCREENSHOT_CONTENT_SCRIPT = `(${measureScreenshotContent.toString()})()`;
+
+/** Keep long pages readable, and rasterize bounded views at their final width. */
+export function contentCapturePlan(bounds, viewport, outputWidth, outputHeight) {
+  const aspect = outputWidth / outputHeight;
+  if (bounds.width / bounds.height < aspect * 0.75) {
+    const width = Math.max(768, Math.ceil((bounds.width + 32) / 8) * 8);
+    return { focus: false, width, height: Math.round(width / aspect), scale: outputWidth / width };
+  }
+  return {
+    focus: true,
+    width: viewport.width,
+    height: viewport.height,
+    scale: Math.min(4, outputWidth / bounds.width),
+  };
+}
+
+export function safeViewportHeight(rectangles, height) {
+  const crossing = rectangles.filter((rect) => rect.top < height && rect.bottom > height
+    && rect.top >= height * 0.85);
+  return crossing.length
+    ? Math.max(Math.ceil(height * 0.85), Math.floor(Math.min(...crossing.map((rect) => rect.top)) - 8))
+    : height;
+}
+
+// End a long-page viewport in whitespace rather than through a text line or
+// control. Only geometry leaves the browser; no page text is returned.
+export const SAFE_VIEWPORT_HEIGHT_SCRIPT = `(() => {
+  const root = document.getElementById('root');
+  if (!root) return innerHeight;
+  const rects = [];
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let node;
+  while ((node = walker.nextNode())) {
+    if (!node.textContent.trim() || getComputedStyle(node.parentElement).visibility !== 'visible') continue;
+    const range = document.createRange(); range.selectNodeContents(node);
+    for (const rect of range.getClientRects()) rects.push({ top: rect.top, bottom: rect.bottom });
+  }
+  for (const control of root.querySelectorAll('button,input,select,textarea')) {
+    const rect = control.getBoundingClientRect();
+    rects.push({ top: rect.top, bottom: rect.bottom });
+  }
+  return (${safeViewportHeight.toString()})(rects, innerHeight);
+})()`;

package/src/runtime/store-screenshot.js

@@ -38,15 +38,17 @@ export function resolveStoreScreenshotAccent(accent, seed = 'notis-app') {
   return ACCENT_NAMES[stableHash(seed) % ACCENT_NAMES.length];
 }
 
-export function storeScreenshotLayout(width = 2000, height = 1250) {
+export function storeScreenshotLayout(width = 2000, height = 1250, contentAspect = STORE_SCREENSHOT_ASPECT) {
+  const aspect = Number.isFinite(contentAspect) && contentAspect > 0
+    ? contentAspect : STORE_SCREENSHOT_ASPECT;
   const horizontalInset = Math.max(48, Math.round(width * 0.06));
   const verticalInset = Math.max(40, Math.round(height * 0.06));
   let cardWidth = width - horizontalInset * 2;
-  let cardHeight = Math.round(cardWidth / STORE_SCREENSHOT_ASPECT);
+  let cardHeight = Math.round(cardWidth / aspect);
   const maximumCardHeight = height - verticalInset * 2;
   if (cardHeight > maximumCardHeight) {
     cardHeight = maximumCardHeight;
-    cardWidth = Math.round(cardHeight * STORE_SCREENSHOT_ASPECT);
+    cardWidth = Math.round(cardHeight * aspect);
   }
   const cardLeft = Math.round((width - cardWidth) / 2);
   const cardTop = Math.round((height - cardHeight) / 2) - Math.round(height * 0.008);
@@ -80,7 +82,7 @@ function roundedRectSvg(width, height, radius, { fill = '#ffffff', stroke = null
 
 /**
  * Composite a truthful browser capture into the deterministic Store frame.
- * The source pixels are only resized/cropped; the app UI is never redrawn.
+ * Fit the complete source pixels; never crop controls or redraw the app UI.
  */
 export async function composeStoreScreenshot({
   inputPath,
@@ -94,13 +96,14 @@ export async function composeStoreScreenshot({
 }) {
   const sharp = await loadSharp();
   const resolvedTheme = theme === 'dark' ? 'dark' : 'light';
-  const layout = storeScreenshotLayout(width, height);
+  const source = await sharp(inputPath).metadata();
+  const layout = storeScreenshotLayout(width, height, source.width / source.height);
   const resolvedAccent = resolveStoreScreenshotAccent(accent, seed);
 
   const roundedCapture = await sharp(inputPath)
     .resize(layout.cardWidth, layout.cardHeight, {
-      fit: 'cover',
-      position: focused ? 'top' : 'centre',
+      fit: 'contain',
+      background: resolvedTheme === 'dark' ? '#09090b' : '#ffffff',
     })
     .composite([{
       input: roundedRectSvg(layout.cardWidth, layout.cardHeight, layout.radius),

package/template/.harness/index.html.tmpl

@@ -93,12 +93,10 @@
       color: hsl(var(--foreground));
       -webkit-font-smoothing: antialiased;
     }
-    #harness-status { position: fixed; top: 0; left: 0; right: 0; padding: 4px 8px; font-size: 11px; background: #111; color: #0f0; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; z-index: 9999; }
-    #root { padding-top: 24px; min-height: 100vh; }
+    #root { min-height: 100vh; }
   </style>
 </head>
 <body>
-  <div id="harness-status">harness: booting</div>
   <div id="root" data-notis-app-root></div>
   <script type="module">
     const routeExport = {{ROUTE_EXPORT}};
@@ -134,10 +132,9 @@
       return Object.prototype.hasOwnProperty.call(tools, name) ? tools[name] : undefined;
     }
 
-    const status = document.getElementById('harness-status');
-    const setStatus = (msg, color = '#0f0') => {
-      status.textContent = `harness: ${msg}`;
-      status.style.color = color;
+    // Boot progress goes to the console so the rendered page stays identical to the app.
+    const setStatus = (msg, failed = false) => {
+      (failed ? console.error : console.info)(`[notis harness] ${msg}`);
     };
 
     window.__harness = {
@@ -416,13 +413,13 @@
           window.__harness.mounted = true;
           const errors = window.__harness.errors.length;
           const calls = window.__harness.runtimeCalls.length;
-          setStatus(`mounted (errors=${errors}, runtimeCalls=${calls})`, errors ? '#f55' : '#0f0');
+          setStatus(`mounted (errors=${errors}, runtimeCalls=${calls})`, errors > 0);
         } catch (error) {
           window.__harness.errors.push({
             type: 'scenario',
             message: error && error.message ? error.message : String(error),
           });
-          setStatus(`scenario failed: ${error && error.message ? error.message : String(error)}`, '#f55');
+          setStatus(`scenario failed: ${error && error.message ? error.message : String(error)}`, true);
         }
       }));
     } catch (error) {
@@ -431,7 +428,7 @@
         message: error && error.message ? error.message : String(error),
         stack: error && error.stack,
       });
-      setStatus(`boot failed: ${error && error.message ? error.message : String(error)}`, '#f55');
+      setStatus(`boot failed: ${error && error.message ? error.message : String(error)}`, true);
     }
   </script>
 </body>