@notis_ai/cli 0.2.0-beta.191.1 → 0.2.0-beta.197.1

package/src/runtime/space-verification.js

@@ -0,0 +1,89 @@
+/** Frozen offline fixtures rendered by the same read-only library as CLI/service. */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { appFilesDigest } from './app-platform.js';
+import { createSpaceFixtureBroker } from './space-fixture-broker.js';
+
+// Kept for the standalone legacy worker's lifecycle tests while that diagnostic
+// entrypoint is retired. The primary verifier below never starts that worker.
+export function spaceVerificationEnvironment(environment, { configPath }) {
+  const names = ['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'LANG', 'SystemRoot', 'WINDIR', 'DISPLAY', 'XDG_RUNTIME_DIR'];
+  return { ...Object.fromEntries(names.filter(name => typeof environment[name] === 'string').map(name => [name, environment[name]])),
+    AGENT_BROWSER_CONFIG: configPath, AGENT_BROWSER_NO_WEBMCP: '1' };
+}
+
+export async function loadSpaceVerificationRenderer() {
+  const candidates = [new URL('../../dist/view-renderer/', import.meta.url), new URL('../../../view-renderer/', import.meta.url)];
+  for (const root of candidates) {
+    const entry = new URL('src/index.js', root);
+    if (!existsSync(fileURLToPath(entry))) continue;
+    const digest = createHash('sha256');
+    for (const file of ['src/renderer.js', 'src/dom.js', 'src/pool.js', 'dist/host.js', 'dist/host.css', 'dist/theme.css']) {
+      digest.update(file); digest.update(readFileSync(new URL(file, root)));
+    }
+    return { ...(await import(entry.href)), rendererDigest: digest.digest('hex') };
+  }
+  throw new Error('The shared view renderer is missing. Rebuild or reinstall this CLI package.');
+}
+
+// One browser per verification, two widths concurrently; no worker creates an
+// unbounded browser fanout. Up to two invocations may run simultaneously.
+let active = 0;
+const waiting = [];
+async function acquire(signal) {
+  if (signal?.aborted) throw new Error('Verification cancelled.');
+  if (active < 2) { active++; return; }
+  if (waiting.length >= 8) throw new Error('The local verification queue is full.');
+  await new Promise((accept, reject) => {
+    const entry = { accept: () => { signal?.removeEventListener('abort', abort); accept(); } };
+    const abort = () => { const index = waiting.indexOf(entry); if(index >= 0) waiting.splice(index, 1); reject(new Error('Verification cancelled.')); };
+    waiting.push(entry); signal?.addEventListener('abort', abort, { once: true });
+  });
+}
+function releaseSlot() { const next = waiting.shift(); if (next) next.accept(); else active--; }
+
+/** Initial deployment checks the exact captured bytes at both product widths. */
+export async function verifySpaceRelease(release, { capabilities, timeoutMs = 45_000, signal, loadRenderer = loadSpaceVerificationRenderer,
+  authorizationMode = 'authorize_missing', unavailableActions = [] } = {}) {
+  const diagnostic = { schema: 'notis-space-render/v1', local_key: release.manifest.local_key,
+    source_digest: appFilesDigest(release.sourceFiles), artifact_digest: appFilesDigest(release.files),
+    mode: 'offline_fixtures', checked_at: new Date().toISOString(),
+    ...(authorizationMode === 'reuse_only' ? { authorization_mode: authorizationMode,
+      unavailable_actions: structuredClone(unavailableActions) } : {}) };
+  if (signal?.aborted) return { ...diagnostic, status: 'failed', errors: [{ phase: 'browser', message: 'Verification cancelled.' }] };
+  if (release.manifest.kind === 'container') return { ...diagnostic, status: 'not_applicable_container' };
+  let pool, held = false, rendererDigest;
+  const brokers = [390, 1440].map(width => ({ width, broker: null }));
+  try {
+    // Validate fixture authority before opening a browser or acquiring a slot.
+    for (const item of brokers) item.broker = createSpaceFixtureBroker({ release, capabilities, width: item.width,
+      authorizationMode, unavailableActions });
+    await acquire(signal); held = true;
+    const library = await loadRenderer(); rendererDigest = library.rendererDigest;
+    pool = library.createBrowserPool({ concurrency: 2, maxQueue: 2 });
+    const observations = await Promise.allSettled(brokers.map(async ({ width, broker }) => {
+      const result = await library.renderView({ broker, pool, outputs: ['markdown', 'screenshot'], width, timeoutMs, signal });
+      const blocked = result.blocked_calls || [];
+      return { width, mounted: true, status: blocked.length ? 'failed' : 'passed',
+        markdown_sha256: createHash('sha256').update(result.markdown).digest('hex'),
+        screenshot_sha256: createHash('sha256').update(Buffer.from(result.screenshot.data_base64, 'base64')).digest('hex'),
+        screenshot_width: result.screenshot.width, screenshot_height: result.screenshot.height,
+        rendered_at: result.rendered_at, blocked_calls: blocked };
+    }));
+    const renders = observations.map((value, index) => value.status === 'fulfilled' ? value.value : {
+      width: brokers[index].width, mounted: false, status: 'failed', error: value.reason?.code || 'render_failed',
+    });
+    const runtimeCalls = brokers.flatMap(({ width, broker }) => broker.calls.map(call => ({ width, ...call })));
+    const passed = renders.every(value => value.status === 'passed') && runtimeCalls.every(call => call.ok);
+    return { ...diagnostic, status: passed ? 'passed' : 'failed', mounted: renders.every(value => value.mounted),
+      fixture_digest: brokers[0].broker.fixtureDigest, renderer_digest: rendererDigest,
+      render_count: renders.length, browser_count: 1, renders, runtimeCalls,
+      errors: passed ? [] : [{ phase: 'renderer', message: 'At least one width or read-only fixture failed verification.' }] };
+  } catch (error) {
+    return { ...diagnostic, status: 'failed', ...(rendererDigest ? { renderer_digest: rendererDigest } : {}),
+      errors: [{ phase: 'harness', message: error.message }] };
+  } finally {
+    try { await pool?.close(); } finally { if (held) releaseSlot(); }
+  }
+}

package/src/runtime/space-verify-browser-worker.js

@@ -0,0 +1,51 @@
+/** Runs in a credential-free child process, never in the authenticated CLI. */
+import { closeAgentBrowserSessionResult, isAgentBrowserAvailable, runHarnessRoute } from './agent-browser.js';
+
+let sessionName;
+let closing;
+let started = false;
+const controller = new AbortController();
+let exitCode = 0;
+const cleanup = () => closing ||= sessionName ? closeAgentBrowserSessionResult(sessionName) : Promise.resolve({ ok: true });
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => {
+  exitCode = signal === 'SIGINT' ? 130 : 143;
+  controller.abort();
+  if (!started) process.exit(exitCode);
+});
+process.on('disconnect', () => { exitCode = 1; controller.abort(); if (!started) process.exit(1); });
+
+process.once('message', async input => {
+  started = true;
+  let result;
+  try {
+    const url = new URL(input.url);
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port
+      || !/^notis-space-[a-f0-9-]+$/.test(input.sessionName)) throw new Error('Invalid offline verification session.');
+    sessionName = input.sessionName;
+    if (!isAgentBrowserAvailable()) throw new Error('Install agent-browser and its Chromium browser to verify a presentation.');
+    const observed = await runHarnessRoute({ url: url.href, sessionName, timeoutMs: input.timeoutMs,
+      designViewports: [], waitForRuntime: true, signal: controller.signal });
+    // Never retain raw eval/stdout or action inputs/results in a diagnostic receipt.
+    result = {
+      mounted: observed.mounted,
+      renderStarted: observed.renderStarted,
+      timed_out: Boolean(observed.timed_out),
+      errors: (observed.errors || []).map(error => ({ phase: String(error.phase).slice(0, 100), message: String(error.message).slice(0, 2000) })),
+      runtimeCalls: (observed.runtimeCalls || []).map(call => ({ actionId: call.actionId, ok: call.ok,
+        ...(call.error ? { error: String(call.error).slice(0, 2000) } : {}) })),
+      ...(observed.tool_error ? { tool_error: { phase: observed.tool_error.phase,
+        message: String(observed.tool_error.stderr || observed.tool_error.message
+          || 'The isolated verification browser could not complete this operation.').slice(0, 2000) } } : {}),
+    };
+  } catch (error) {
+    result = { mounted: false, errors: [{ phase: 'browser', message: error.message }], runtimeCalls: [] };
+  } finally {
+    if (process.connected) {
+      try { process.send({ phase: 'cleanup' }, () => {}); } catch { /* Cleanup still owns the browser after IPC loss. */ }
+    }
+    const closed = await cleanup();
+    result = { ...result, cleanup: closed, ...(!closed.ok ? { cleanup_failed: true } : {}) };
+  }
+  if (process.connected) process.send(result, () => process.exit(exitCode));
+  else process.exit(exitCode);
+});

package/src/runtime/space-view-manifest.js

@@ -0,0 +1,254 @@
+/**
+ * What a view declares (V4): path, typed params, shows, memory, chrome and a Markdown override.
+ * Mirrors server/lib/space_view_manifest.py, which re-checks every release; property-level checks
+ * need the linked schemas and run on the server during `spaces verify` and deploy.
+ * Every presentation requires path, description and memory, including sources that omit
+ * specVersion. Containers remain non-executable; explicit specVersion 2 is unchanged.
+ */
+import { usageError } from './errors.js';
+import portalRouteRoots from '../../config/portal-route-roots.json' with { type: 'json' };
+const RESERVED_PATHS = new Set(portalRouteRoots);
+
+export const VIEW_SPEC_VERSION = 2;
+export const VIEW_DEFINITION_FIELDS = Object.freeze(['specVersion', 'path', 'params', 'shows', 'memory', 'chrome', 'markdown']);
+export const VIEW_PARAM_TYPES = Object.freeze(['record', 'enum', 'text', 'number', 'date', 'boolean']);
+const RESERVED_PARAMS = new Set(['record', 'assistantThread']);
+const PAGE_ONLY = ['params', 'shows', 'memory', 'chrome', 'markdown'];
+const NAME = /^[a-z][A-Za-z0-9_]{0,63}$/;
+// Credentials never ride in links, so no view param may look like one (the Portal drops these names).
+const CREDENTIAL_PARAM = /^(?:jwt|code|state|key)$|token|secret|password|credential|session|auth|api_?key/i;
+const WORD = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ID_TAIL = /(?:^|-)(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+const PLACEHOLDER = /^\{([a-z][A-Za-z0-9_]{0,63})(?:\.([^{}.\s][^{}]{0,199}))?\}$/;
+const RECORD_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const SERVICE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const FIELD_KEYS = ['property', 'property_id', 'column'];
+const OPS = new Set(['equals', 'not_equals', 'in', 'contains', 'not_contains', 'starts_with', 'ends_with', 'is_empty', 'is_not_empty',
+  'greater_than', 'less_than', 'greater_than_or_equal_to', 'less_than_or_equal_to', 'does_not_contain', 'before', 'after',
+  'on_or_before', 'on_or_after']);
+const CRON_BOUNDS = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]];
+const DEBOUNCE = [60, 86400];
+
+const plain = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const text = (value, limit) => typeof value === 'string' && value.trim().length >= 1 && value.trim().length <= limit && !CONTROL.test(value);
+const isoDate = value => typeof value === 'string' && DATE.test(value) && !Number.isNaN(Date.parse(`${value}T00:00:00Z`))
+  && new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) === value;
+
+export function validateViewPath(value) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > 100) {
+    throw usageError('Declare path as the words of this view\'s links, such as "notes" or "seo/keywords".');
+  }
+  const segments = value.split('/');
+  if (segments.length > 4 || segments.some(segment => !WORD.test(segment) || ID_TAIL.test(segment))) {
+    throw usageError('A path is up to four lowercase words (a-z, 0-9, dashes) separated by "/", without ids.');
+  }
+  if (RESERVED_PATHS.has(segments[0])) throw usageError(`The path "${segments[0]}" belongs to the Portal. Choose another first word.`);
+  return value;
+}
+
+function validCron(value) {
+  const fields = typeof value === 'string' ? value.split(' ') : [];
+  if (fields.length !== 5) return false;
+  return fields.every((field, index) => {
+    const [low, high] = CRON_BOUNDS[index];
+    const inRange = number => /^\d+$/.test(number) && Number(number) >= low && Number(number) <= high;
+    if (index === 0) return inRange(field);
+    return field.split(',').every(part => {
+      const [base, step, extra] = part.split('/');
+      if (extra !== undefined || (step !== undefined && !(/^\d+$/.test(step) && Number(step) >= 1 && Number(step) <= high))) return false;
+      if (base === '*') return true;
+      const [start, end, more] = base.split('-');
+      if (more !== undefined || !inRange(start) || (end !== undefined && (!inRange(end) || Number(start) > Number(end)))) return false;
+      return true;
+    });
+  });
+}
+
+function validateMemory(memory) {
+  if (!plain(memory) || Object.keys(memory).sort().join(',') !== 'attachments,markdown,screenshot,snapshots') {
+    throw usageError('Declare memory as { markdown, attachments, screenshot, snapshots }; see the memory guide.');
+  }
+  if (['markdown', 'attachments', 'screenshot'].some(name => typeof memory[name] !== 'boolean')) {
+    throw usageError('memory.markdown, memory.attachments and memory.screenshot are true or false.');
+  }
+  if (!Array.isArray(memory.snapshots) || memory.snapshots.length > 3) {
+    throw usageError('memory.snapshots lists on_render, { scheduled } and { on_change }, each at most once ([] for none).');
+  }
+  const seen = new Set();
+  for (const strategy of memory.snapshots) {
+    let kind;
+    if (strategy === 'on_render') kind = 'on_render';
+    else if (plain(strategy) && Object.keys(strategy).join(',') === 'scheduled') {
+      kind = 'scheduled';
+      if (!validCron(strategy.scheduled)) throw usageError('A scheduled snapshot uses a five-field UTC cron with a fixed minute, such as "0 7 * * 1".');
+    } else if (plain(strategy) && Object.keys(strategy).join(',') === 'on_change') {
+      kind = 'on_change';
+      const debounce = strategy.on_change?.debounceSeconds;
+      if (!plain(strategy.on_change) || Object.keys(strategy.on_change).join(',') !== 'debounceSeconds' || !Number.isInteger(debounce)
+        || debounce < DEBOUNCE[0] || debounce > DEBOUNCE[1]) {
+        throw usageError(`An on_change snapshot waits debounceSeconds (${DEBOUNCE[0]} to ${DEBOUNCE[1]}) after the last change.`);
+      }
+    } else throw usageError('memory.snapshots lists on_render, { scheduled: "<cron>" } or { on_change: { debounceSeconds } }.');
+    if (seen.has(kind)) throw usageError('Declare each memory snapshot strategy at most once.');
+    seen.add(kind);
+  }
+}
+
+/** One typed param value, as the SDK and the server accept it. */
+export function viewParamValue(declaration, value) {
+  switch (declaration.type) {
+    case 'text': return typeof value === 'string' && value.length <= 500 && !CONTROL.test(value);
+    case 'enum': return typeof value === 'string' && (declaration.values || []).includes(value);
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'date': return isoDate(value);
+    case 'record': return typeof value === 'string' && RECORD_KEY.test(value);
+    default: return false;
+  }
+}
+
+function validateParam(name, declaration, resources) {
+  if (!NAME.test(name) || RESERVED_PARAMS.has(name) || CREDENTIAL_PARAM.test(name)) throw usageError(`Param names are camelCase words; "${name}" is not available.`);
+  const allowed = new Set(['type', 'description', 'required', 'default', 'values', 'database', 'main', 'slugProperty']);
+  if (!plain(declaration) || Object.keys(declaration).some(field => !allowed.has(field)) || !VIEW_PARAM_TYPES.includes(declaration.type)) {
+    throw usageError(`Declare param "${name}" as { type, description, ... } with type ${VIEW_PARAM_TYPES.join(', ')}.`);
+  }
+  if (!text(declaration.description, 500)) throw usageError(`Describe param "${name}": what it selects, for agents and people.`);
+  if ('required' in declaration && typeof declaration.required !== 'boolean') throw usageError(`Param "${name}": required is true or false.`);
+  if (declaration.type === 'enum') {
+    const values = declaration.values;
+    if (!Array.isArray(values) || values.length < 1 || values.length > 100 || new Set(values).size !== values.length
+      || values.some(value => !text(value, 100))) throw usageError(`Param "${name}": an enum lists its distinct values.`);
+  } else if ('values' in declaration) throw usageError(`Param "${name}": only enum params list values.`);
+  if (declaration.type === 'record') {
+    if (resources[declaration.database]?.kind !== 'database') {
+      throw usageError(`Param "${name}": a record param names a database this Space declares in resources.`);
+    }
+    if ('main' in declaration && typeof declaration.main !== 'boolean') throw usageError(`Param "${name}": main is true or false.`);
+    if ('slugProperty' in declaration && !text(declaration.slugProperty, 200)) throw usageError(`Param "${name}": slugProperty names a property of its database.`);
+    if ('default' in declaration) throw usageError(`Param "${name}": a record param has no default record.`);
+  } else if (['database', 'main', 'slugProperty'].some(field => field in declaration)) {
+    throw usageError(`Param "${name}": database, main and slugProperty belong to record params.`);
+  }
+  if ('default' in declaration) {
+    if (declaration.required === true) throw usageError(`Param "${name}": a required param has no default.`);
+    if (!viewParamValue(declaration, declaration.default)) throw usageError(`Param "${name}": its default must be a valid ${declaration.type} value.`);
+  }
+}
+
+function checkPlaceholder(value, params, collection, where) {
+  const match = typeof value === 'string' ? PLACEHOLDER.exec(value) : null;
+  if (!match) return;
+  const [, name, property] = match;
+  if (name === 'record') {
+    const records = Object.values(params).filter(declaration => declaration.type === 'record');
+    if (records.length === 1 || (!records.length && collection)) return;
+    throw usageError('Use {record} only in a view with exactly one record param (or a collection); otherwise name the param, such as {project}.');
+  }
+  if (!Object.hasOwn(params, name)) throw usageError(`${where}: "{${name}}" names no declared param.`);
+  if (property !== undefined && params[name].type !== 'record') throw usageError(`${where}: only record params have properties, such as {${name}}.`);
+}
+
+function walkFilter(node, visit, where, depth = 0, budget = { left: 200 }) {
+  budget.left -= 1;
+  if (depth > 12 || budget.left < 0) throw usageError(`${where}: the filter is too complex; use fewer conditions.`);
+  if (depth === 0 && plain(node) && !Object.keys(node).length) return;
+  if (!plain(node)) throw usageError(`${where}: a filter is an object.`);
+  for (const group of ['and', 'or']) {
+    if (!Object.hasOwn(node, group)) continue;
+    const children = node[group];
+    if (Object.keys(node).length !== 1 || !Array.isArray(children) || !children.length) throw usageError(`${where}: filter groups need at least one condition.`);
+    children.forEach(child => walkFilter(child, visit, where, depth + 1, budget));
+    return;
+  }
+  const field = node.field;
+  if (Object.keys(node).some(key => !['field', 'op', 'value'].includes(key)) || !('field' in node) || !('op' in node)
+    || !plain(field) || Object.keys(field).length !== 1 || !FIELD_KEYS.includes(Object.keys(field)[0])
+    || typeof Object.values(field)[0] !== 'string' || !OPS.has(node.op)) {
+    throw usageError(`${where}: each condition is { field: { property }, op, value } in the native filter language.`);
+  }
+  visit(node);
+}
+
+function validateShows(name, declaration, params, resources, collection) {
+  const where = `shows.${name}`;
+  if (!NAME.test(name)) throw usageError(`Shows names are camelCase words; "${name}" is not available.`);
+  if (plain(declaration) && 'about' in declaration) {
+    const services = declaration.services ?? [];
+    if (Object.keys(declaration).some(field => !['about', 'services'].includes(field)) || !text(declaration.about, 500)
+      || !Array.isArray(services) || services.length > 20 || services.some(service => typeof service !== 'string' || !SERVICE.test(service))) {
+      throw usageError(`${where}: describe what it shows as { about, services? }.`);
+    }
+    return;
+  }
+  if (!plain(declaration) || Object.keys(declaration).some(field => !['database', 'where', 'open'].includes(field)) || !('where' in declaration)) {
+    throw usageError(`${where}: declare { database, where, open? } for Notis data or { about, services? } otherwise.`);
+  }
+  if (resources[declaration.database]?.kind !== 'database') {
+    throw usageError(`${where}: "${declaration.database}" is not a database this Space declares and links.`);
+  }
+  if (declaration.open !== undefined && (params[declaration.open]?.type !== 'record' || params[declaration.open].database !== declaration.database)) {
+    throw usageError(`${where}: open names a record param over the same database.`);
+  }
+  walkFilter(declaration.where, condition => {
+    if (!('value' in condition)) return;
+    const values = condition.op === 'in' && Array.isArray(condition.value) ? condition.value : [condition.value];
+    values.forEach(value => checkPlaceholder(value, params, collection, where));
+  }, where);
+}
+
+/**
+ * Validates V4 declarations independently of the optional version marker, then returns
+ * their manifest form without inventing a version or page fields for containers.
+ */
+export function viewManifestFields(definition, { entry, resources }) {
+  const container = !entry;
+  const version = definition.specVersion;
+  if (version !== undefined && version !== VIEW_SPEC_VERSION) throw usageError(`specVersion is ${VIEW_SPEC_VERSION} for sources that declare the view manifest.`);
+  if (container && PAGE_ONLY.some(field => definition[field] !== undefined)) {
+    throw usageError('A container has no page: params, shows, memory, chrome and markdown belong to its views.');
+  }
+  if (!container || version === VIEW_SPEC_VERSION) {
+    const missing = ['path', 'description'].filter(field => !definition[field]);
+    if (!container && definition.memory === undefined) missing.push('memory');
+    if (missing.length) throw usageError(`This view needs ${missing.join(', ')} (specVersion 2).`);
+    if (!text(definition.description, 300)) throw usageError('Describe this view in one line (up to 300 characters).');
+  }
+  if (definition.path !== undefined) validateViewPath(definition.path);
+  const params = definition.params ?? {};
+  if (definition.params !== undefined) {
+    if (!plain(params) || Object.keys(params).length > 50) throw usageError('Declare params as { name: { type, description, ... } }.');
+    const mains = new Map();
+    for (const [name, declaration] of Object.entries(params)) {
+      validateParam(name, declaration, resources);
+      if (declaration.type !== 'record' || declaration.main !== true) continue;
+      if (mains.has(declaration.database)) {
+        throw usageError(`Params "${mains.get(declaration.database)}" and "${name}" both claim main for database "${declaration.database}"; a database has one main view.`);
+      }
+      mains.set(declaration.database, name);
+    }
+  }
+  if (definition.shows !== undefined) {
+    if (!plain(definition.shows) || Object.keys(definition.shows).length > 50) {
+      throw usageError('Declare shows as { name: { database, where, open? } } or { name: { about, services? } }.');
+    }
+    for (const [name, declaration] of Object.entries(definition.shows)) validateShows(name, declaration, params, resources, definition.collection);
+  }
+  if (definition.memory !== undefined) validateMemory(definition.memory);
+  if (definition.chrome !== undefined && !['portal', 'hidden'].includes(definition.chrome)) throw usageError("chrome is 'portal' (default) or 'hidden'.");
+  if (definition.markdown !== undefined && (typeof definition.markdown !== 'string' || !definition.markdown)) {
+    throw usageError('markdown names a source module whose default export renders this view as Markdown.');
+  }
+  return {
+    ...(version !== undefined ? { spec_version: version } : {}),
+    ...(definition.path !== undefined ? { path: definition.path } : {}),
+    ...(definition.params !== undefined ? { params } : {}),
+    ...(definition.shows !== undefined ? { shows: definition.shows } : {}),
+    ...(definition.memory !== undefined ? { memory: definition.memory } : {}),
+    ...(definition.chrome !== undefined ? { chrome: definition.chrome } : {}),
+    ...(definition.markdown !== undefined ? { markdown: { export_name: 'SpaceMarkdown' } } : {}),
+  };
+}

package/src/runtime/sync-skills.js

@@ -218,7 +218,7 @@ export async function reconcileAllSkills({
       serverUrl,
       jwt,
       {},
-      { honorSyncEnabled },
+      { honorSyncEnabled, ...(home ? { syncHome: home } : {}) },
     );
     return {
       ...account,

package/src/runtime/transport.js

@@ -82,10 +82,15 @@ function createMultipartFileUpload(payload, bindingMetadata, fileBindings) {
   };
 }
 
-function normalizeBackendError(status, payload, runtime) {
+export function normalizeBackendError(status, payload, runtime) {
   const backendError = payload?.error;
+  // Space errors answer {error: <stable code>, message: <readable text>}: show
+  // the text (it can name the Space involved); the code stays in details.
+  const codedMessage = typeof backendError === 'string' && /^[a-z][a-z0-9_]*$/.test(backendError)
+    && typeof payload?.message === 'string' && payload.message ? payload.message : null;
   const message =
     backendError?.message ||
+    codedMessage ||
     backendError ||
     payload?.message ||
     payload?.error ||
@@ -258,6 +263,7 @@ export async function httpRequest({
   body,
   multipart = false,
   requireAuth = true,
+  spacesProtocol,
 }) {
   // Refresh before spending the credential rather than after a rejection: the
   // rotating refresh token is shared with every other `notis` process reading
@@ -293,6 +299,7 @@ export async function httpRequest({
     'X-Notis-CLI-Version': runtime.cliVersion,
     'X-Notis-Request-Id': requestId,
   };
+  if (spacesProtocol !== undefined) headers['X-Notis-Spaces-Protocol'] = String(spacesProtocol);
   if (!multipart) {
     headers['Content-Type'] = 'application/json';
   }

package/src/runtime/view-render.js

@@ -0,0 +1,49 @@
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile, unlink } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { httpRequest } from './transport.js';
+import { CliError, EXIT_CODES, usageError } from './errors.js';
+
+async function rendererLibrary() {
+  const packaged = new URL('../../dist/view-renderer/src/index.js', import.meta.url);
+  if (existsSync(fileURLToPath(packaged))) return import(packaged.href);
+  const development = new URL('../../../view-renderer/src/index.js', import.meta.url);
+  if (existsSync(fileURLToPath(development))) return import(development.href);
+  throw usageError('The shared view renderer is missing. Rebuild or reinstall this CLI package.');
+}
+
+/** Root command registration supplies flags/output formatting; this adapter holds no browser JWT. */
+export async function renderViewWithCliRuntime({ runtime, url, outputs = ['markdown', 'screenshot'], width = 1440,
+  directory, signal, loadLibrary = rendererLibrary, request = httpRequest }) {
+  if (typeof url !== 'string' || !url.trim() || ![390, 1440].includes(width)) throw usageError('Choose a view link and width 390 or 1440.');
+  const ticket = (await request({ runtime, method: 'POST', path: '/portal_view_render/prepare', spacesProtocol: 1,
+    body: { url, outputs, width }, signal })).payload;
+  if (typeof ticket?.credential !== 'string') throw usageError('The short-lived render ticket is missing.');
+  const library = await loadLibrary();
+  const broker = library.createRemoteRenderBroker({ apiBase: runtime.apiBase, credential: ticket.credential });
+  let result;
+  try {
+    result = await library.renderView({ broker, outputs, width, signal });
+    await broker.complete(result, { signal });
+  }
+  catch (error) {
+    if (error instanceof library.ViewRenderError) throw new CliError({ code: error.code,
+      message: error.message, exitCode: EXIT_CODES.backend, retryable: error.status >= 500 || error.status === 429, cause: error });
+    throw error;
+  }
+  if (!directory) return { result, artifacts: null };
+  const root = resolve(directory), created = [], artifacts = {};
+  await mkdir(root, { recursive: true });
+  try {
+    for (const [kind, name, bytes] of [
+      ['markdown', 'view.md', result.markdown === undefined ? undefined : Buffer.from(result.markdown, 'utf8')],
+      ['screenshot', 'view.png', result.screenshot ? Buffer.from(result.screenshot.data_base64, 'base64') : undefined],
+    ]) {
+      if (bytes === undefined) continue;
+      const path = join(root, name);
+      await writeFile(path, bytes, { flag: 'wx', mode: 0o600 }); created.push(path); artifacts[kind] = path;
+    }
+  } catch (error) { await Promise.allSettled(created.map(path => unlink(path))); throw error; }
+  return { result, artifacts };
+}

package/src/space-harness-host.ts

@@ -0,0 +1,103 @@
+import React from 'react';
+import * as ReactDOM from 'react-dom';
+import * as ReactDOMClient from 'react-dom/client';
+import * as JSXRuntime from 'react/jsx-runtime';
+import { importBundleSource, resolveBundleRouteExport } from '../../sdk/src/bundleModule';
+import { SdkPresentation } from '../../sdk/src/presentation';
+import { createPrefetchQueue, createQueryClient } from '../../sdk/src/queryCache';
+import type { NotisRuntime } from '../../sdk/src/runtime';
+import { SPACE_VIEWER_READ_OPERATIONS } from '../../sdk/src/space';
+import type { SpaceActionOptions, SpaceDocumentBodyRequest, SpaceViewerReadOperation } from '../../sdk/src/space';
+
+type Call = { op: string; actionId?: string; ok: boolean | null; error?: string };
+const state = { mounted: false, renderStarted: false, errors: [] as Array<{ phase: string; message: string }>, runtimeCalls: [] as Call[] };
+Object.assign(window, { __harness: state, React, ReactDOM, ReactDOMClient, __ReactJSXRuntime: JSXRuntime });
+const diagnostic = (phase: string, reason: unknown) => state.errors.push({ phase,
+  message: reason instanceof Error ? reason.message : String(reason || 'Verification failed.') });
+window.addEventListener('error', event => diagnostic('window_error', event.error || event.message));
+window.addEventListener('unhandledrejection', event => diagnostic('unhandled_rejection', event.reason));
+window.addEventListener('securitypolicyviolation', event => diagnostic('security_policy', `Blocked ${event.violatedDirective}`));
+
+async function start() {
+  const response = await fetch('/snapshot', { credentials: 'omit' });
+  if (!response.ok) throw new Error('The frozen verification snapshot could not be loaded.');
+  const snapshot = await response.json();
+  const authority = structuredClone(snapshot.descriptor.space);
+  const runFixture = async (call: Call, input: unknown) => {
+    state.runtimeCalls.push(call);
+    try {
+      const result = await fetch('/fixture', { method: 'POST', credentials: 'omit',
+        headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input), signal: AbortSignal.timeout(5_000) });
+      const payload = await result.json();
+      if (!result.ok) throw new Error(payload.message || 'No matching synthetic fixture.');
+      call.ok = true; return payload.result;
+    } catch (error) {
+      call.ok = false; call.error = error instanceof Error ? error.message : 'Verification request failed.';
+      throw error;
+    }
+  };
+  const protocolFailure = (message: string): Promise<never> => { diagnostic('protocol', message); return Promise.reject(new Error(message)); };
+  const deny = () => protocolFailure('Use a declared Space action.');
+  const queue = createPrefetchQueue(2);
+  const runtime: NotisRuntime = {
+    ...snapshot.descriptor, databases: [],
+    context: { ...snapshot.descriptor.context,
+      resourceId: snapshot.descriptor.context?.resource_id ?? snapshot.descriptor.context?.resourceId ?? null,
+      collectionItem: snapshot.descriptor.context?.collection_item ?? snapshot.descriptor.context?.collectionItem ?? null },
+    queryClient: createQueryClient({ maxEntries: 100, schedule: queue }),
+    listTools: deny, callTool: deny, request: deny,
+    callAction<T>(id: string, inputs: Record<string, unknown> = {}, options: SpaceActionOptions = {}): Promise<T> {
+      if (!Object.hasOwn(authority.actions, id)) return protocolFailure('Undeclared verification action.');
+      if ((options.readOnly || options.dedupe) && authority.actions[id].readOnly !== true) {
+        return protocolFailure('A write action cannot run as a cached read.');
+      }
+      return runFixture({ op: 'callAction', actionId: id, ok: null }, { action_id: id, inputs });
+    },
+    viewerRead: authority.viewerReads?.length ? <T,>(operation: SpaceViewerReadOperation, input: Record<string, unknown> = {}): Promise<T> => {
+      const family = Object.hasOwn(SPACE_VIEWER_READ_OPERATIONS, operation) ? SPACE_VIEWER_READ_OPERATIONS[operation] : null;
+      if (!family || !authority.viewerReads.includes(family)) return protocolFailure('Undeclared verification viewer read.');
+      return runFixture({ op: 'viewerRead', actionId: operation, ok: null }, { viewer_read: { operation, input } });
+    } : undefined,
+    shown: Object.values(authority.shows || {}).some(list => 'database' in list) ? <T,>(name: string, params: Record<string, unknown> = {}): Promise<T> => {
+      const list = authority.shows && Object.hasOwn(authority.shows, name) ? authority.shows[name] : null;
+      if (!list || !('database' in list)) return protocolFailure('Undeclared verification list.');
+      return runFixture({ op: 'shown', actionId: name, ok: null }, { shown: { name, params } });
+    } : undefined,
+    documentBody(request: SpaceDocumentBodyRequest) {
+      return runFixture({ op: 'documentBody', actionId: request?.readAction, ok: null }, { document_body: request });
+    },
+    navigate(payload) {
+      if (payload.kind !== 'space-reference' || typeof payload.alias !== 'string' || !authority.navigation?.includes(payload.alias)) {
+        return protocolFailure('Offline navigation requires a declared synthetic destination.');
+      }
+      // This observes a declaration only; no live navigation or access is claimed.
+      state.runtimeCalls.push({ op: 'navigate', actionId: payload.alias, ok: true });
+    },
+    publishActiveResource() {}, captureContextSelection() {},
+    addContext: async () => false, updateContext: async () => false, removeContext: async () => false,
+    registerTopBarSearch() {}, setTopBarSearchValue() {}, setTopBarSearchLoading() {},
+  };
+  const module = await importBundleSource(snapshot.source);
+  const view = resolveBundleRouteExport(module, ['SpaceView'], true);
+  if (!view) throw new Error('The SpaceView export is missing from this presentation.');
+  const host = document.createElement('div'); host.style.cssText = 'min-height:100vh;height:100vh';
+  const shadow = host.attachShadow({ mode: 'open' });
+  const css = document.createElement('style'); css.textContent = snapshot.css; shadow.appendChild(css);
+  const mount = document.createElement('div'); mount.setAttribute('data-notis-app-mount', 'true');
+  mount.style.cssText = 'min-height:0;height:100%'; shadow.appendChild(mount);
+  document.body.appendChild(host);
+  const controller = document.createElement('div'); document.body.appendChild(controller);
+  const mode = new URLSearchParams(location.search).get('theme') === 'dark' ? 'dark' : 'light';
+  document.documentElement.classList.toggle('dark', mode === 'dark');
+  state.renderStarted = true;
+  ReactDOMClient.createRoot(controller).render(React.createElement(SdkPresentation, {
+    mount, runtime, component: view.component, shell: module.__AppShell, theme: { mode, style: { colorScheme: mode } },
+    resetKey: snapshot.cacheKey,
+    onCommit: (hasContent: boolean) => { state.mounted = hasContent; },
+    onError: (error: Error) => { state.mounted = false; state.errors.push({ phase: 'render', message: error.message }); },
+    onProtocolError: (error: Error) => diagnostic('protocol', error),
+    fallback: (error: Error) => React.createElement('div', { role: 'alert' }, error.message),
+  }));
+}
+
+void start().catch(reason => state.errors.push({ phase: 'boot', message: reason instanceof Error ? reason.message : 'Verification did not start.' }));

package/template/app/globals.css

@@ -3,6 +3,7 @@
 @config "../tailwind.config.ts";
 @source "./";
 @source "../components";
+@source "../spaces";
 @source "../lib";
 @source "../packages/sdk/src";