@notis_ai/cli 0.2.0-beta.177.1 → 0.2.0-beta.179.1

package/src/runtime/agent-browser.js

@@ -1,6 +1,7 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { contentCapturePlan, MEASURE_SCREENSHOT_CONTENT_SCRIPT, SAFE_VIEWPORT_HEIGHT_SCRIPT } from './screenshot-framing.js';
 
 export const HIDE_HARNESS_STATUS_SCRIPT =
   "(() => { const el = document.getElementById('harness-status'); if (el) el.style.opacity = '0'; return true; })()";
@@ -228,6 +229,7 @@ export async function runHarnessRoute({
   timeoutMs = 10_000,
   snapshotPath = null,
   designViewports = DEFAULT_DESIGN_VIEWPORTS,
+  waitForRuntime = false,
 }) {
   const opened = await runAgentBrowser(['--session', sessionName, 'open', url], {
     timeoutMs: Math.min(Math.max(timeoutMs, 5000), 30_000),
@@ -244,17 +246,21 @@ export async function runHarnessRoute({
   }
 
   const deadline = Date.now() + timeoutMs;
+  let readySince = null;
   while (Date.now() < deadline) {
     const lastRead = await readHarness(sessionName, 5000);
     if (!lastRead.ok) {
+      readySince = null;
       await delay(250);
       continue;
     }
     const harness = lastRead.harness;
-    if (harness?.mounted || (Array.isArray(harness?.errors) && harness.errors.length > 0)) {
-      await delay(250);
-      break;
-    }
+    if (Array.isArray(harness?.errors) && harness.errors.length > 0) break;
+    const pending = (harness?.runtimeCalls || []).some(call => call?.ok == null);
+    if (harness?.mounted && (!waitForRuntime || !pending)) {
+      readySince ??= Date.now();
+      if (Date.now() - readySince >= 250) break;
+    } else readySince = null;
     await delay(250);
   }
 
@@ -283,8 +289,8 @@ export async function runHarnessRoute({
     }
   }
 
-  const timedOut = !harness.mounted && Date.now() >= deadline;
   const runtimeCalls = Array.isArray(harness.runtimeCalls) ? harness.runtimeCalls : [];
+  const timedOut = (!harness.mounted || (waitForRuntime && runtimeCalls.some(call => call?.ok == null))) && Date.now() >= deadline;
 
   // Design assertions only mean something on a mounted route. Loading
   // placeholders are excused while a runtime call is still in flight.
@@ -317,18 +323,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,
@@ -428,13 +434,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 });
@@ -446,7 +489,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(
@@ -459,10 +508,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,
     };
   }

package/src/runtime/app-platform.js

@@ -286,13 +286,14 @@ export function detectProjectWarnings(projectDir, appConfig = null) {
     appConfig?.capabilities?.workspaceDatabases === 'read';
   if (
     appConfig
+    && appConfig.kind !== 'report'
     && !readsWorkspaceDatabases
     && (!Array.isArray(appConfig.databases) || appConfig.databases.length === 0)
   ) {
     warnings.push('No database references declared in notis.config.ts.');
   }
 
-  if (appConfig) {
+  if (appConfig && appConfig.kind !== 'report') {
     try {
       const listing = inspectListingReadiness(projectDir, appConfig);
       warnings.push(...listing.errors, ...listing.warnings);
@@ -813,6 +814,29 @@ export function generateManifest(appConfig, projectDir) {
     return entry;
   });
 
+  if (appConfig.kind === 'report') {
+    if (routes.length !== 1 || routes[0].collection || routes[0].resourceDeepLinks) {
+      throw usageError('Reports require one standalone route, without app collections or resource deep links.');
+    }
+    if (['databases', 'skills', 'automations', 'onboarding', 'tagline', 'categories', 'author', 'screenshots'].some(key => {
+      const value = appConfig[key];
+      return Array.isArray(value) ? value.length > 0 : Boolean(value);
+    })) throw usageError('Reports cannot own databases, skills, automations or Store metadata.');
+    if (Object.values(appConfig.capabilities || {}).some(value => value !== 'read')) {
+      throw usageError('Reports support read capabilities only; shell grants require an installed app.');
+    }
+    const databaseAccess = appConfig.databaseAccess || [];
+    if (!Array.isArray(databaseAccess) || databaseAccess.some(entry =>
+      !entry || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(entry.id || '') ||
+      !['read', 'write'].includes(entry.access)
+    )) throw usageError('databaseAccess entries require an existing database UUID and read/write access.');
+    return { kind: 'report', version: 1, spec_version: 4,
+      routes: routes.map(route => ({ ...route, default: true, tool_access: { base: { tools: appConfig.tools || [] } } })),
+      bundle: { js: 'bundle/app.js', css: 'bundle/app.css' },
+      tools: appConfig.tools || [], tool_bindings: normalizeAppToolBindings(appConfig.toolBindings),
+      capabilities: normalizeAppCapabilities(appConfig.capabilities), database_access: databaseAccess };
+  }
+
   // Database entries may be a bare slug (structure only) or an object opting
   // into shipping rows to installers. Normalize to the manifest's snake_case.
   const databases = (appConfig.databases || []).map((entry) => {

package/src/runtime/app-test-server.js

@@ -164,6 +164,7 @@ function buildHarnessDescriptor({ state, manifest, appConfig, route, scenario =
   );
 
   return {
+    ...(state.resource ? { resource: state.resource } : {}),
     app: {
       id: state.appId || 'harness-app',
       slug: state.slug,

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

@@ -207,8 +207,8 @@
     }
 
     async function runtimeQuery(body) {
-      if (!apiBase || !jwt || !descriptor.app || !descriptor.app.id) {
-        throw new Error('live harness mode requires apiBase, jwt, and app id');
+      if (!apiBase || !jwt || !(descriptor.resource?.kind === 'report' ? descriptor.resource.id : descriptor.app?.id)) {
+        throw new Error('live harness mode requires apiBase, jwt, and runtime resource identity');
       }
       const response = await fetch(`${String(apiBase).replace(/\/$/, '')}/portal_views/runtime_query`, {
         method: 'POST',
@@ -217,7 +217,9 @@
           Authorization: `Bearer ${jwt}`,
         },
         body: JSON.stringify({
-          app_id: descriptor.app.id,
+          ...(descriptor.resource?.kind === 'report'
+            ? { document_id: descriptor.resource.id, revision: descriptor.resource.revision }
+            : { app_id: descriptor.app.id }),
           route_slug: descriptor.route && descriptor.route.slug,
           ...body,
         }),
@@ -230,7 +232,10 @@
       if (!payload) {
         throw new Error(snippet ? `Runtime response was not JSON: ${snippet}` : 'Runtime response was empty');
       }
-      if (payload.status === 'error' || payload.error) {
+      if (payload.status === 'error' || payload.error || (descriptor.resource?.kind === 'report' && (
+        ['error', 'failed', 'failure'].includes(String(payload.status || '').trim().toLowerCase())
+        || payload.ok === false || payload.success === false || payload.successful === false
+      ))) {
         throw new Error(payload.message || payload.error || 'Runtime request failed');
       }
       return payload;
@@ -238,6 +243,7 @@
 
     function stubRuntime() {
       return {
+        resource: descriptor.resource,
         app: descriptor.app,
         route: descriptor.route,
         context: descriptor.context || {},
@@ -287,6 +293,7 @@
         request: async (path, options) => tracked(
           record('request', { path, options }),
           async () => {
+            if (descriptor.resource?.kind === 'report') throw new Error('Reports access data through declared tools.');
             if (fixtures && fixtures.requests && Object.prototype.hasOwnProperty.call(fixtures.requests, path)) {
               return structuredClone(fixtures.requests[path]);
             }
@@ -349,6 +356,7 @@
         request: async (path, options) => tracked(
           record('request', { path, options }),
           async () => {
+            if (descriptor.resource?.kind === 'report') throw new Error('Reports access data through declared tools.');
             const response = await fetch(`${String(apiBase).replace(/\/$/, '')}${path}`, {
               method: (options && options.method) || 'GET',
               headers: {