@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.5

package/packages/identity/tests/oauth-consent-view.test.mjs

@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildOAuthConsentView,
+  normalizeOAuthConsentCompany,
+  renderOAuthConsentHtml,
+} from '../src/oauth/consent-view.js';
+
+test('OAuth consent uses company as issuer brand SSOT without product-specific copy', () => {
+  const company = normalizeOAuthConsentCompany({
+    id: 'co_default',
+    name: 'Fuel & Free Time',
+    logo_url: 'https://assets.example.test/logo.png',
+    primary_color: '#f15a24',
+    auth_bg_color: '#101214',
+  });
+  const view = buildOAuthConsentView({
+    company,
+    resource: {
+      id: 'res_fnf_mcp',
+      audience: 'https://fuelnfreetime.com/mcp',
+      display_name: 'Fuel & Free Time MCP',
+      description: 'Store, content, and experience tools.',
+    },
+    client: {
+      client_id: 'chatgpt',
+      display_name: 'ChatGPT',
+    },
+    signed_in_email: 'customer@example.test',
+    scopes: [
+      {
+        scope: 'fnf:store.read',
+        label: 'Store data',
+        description: 'Read published store and CMS data.',
+        sort_order: 20,
+      },
+      {
+        scope: 'fnf:experience.read',
+        label: 'Interactive experiences',
+        description: 'Read published interactive scene metadata.',
+        sort_order: 10,
+      },
+    ],
+  });
+
+  assert.equal(view.issuer.name, 'Fuel & Free Time');
+  assert.equal(view.issuer.primaryColor, '#f15a24');
+  assert.equal(view.copy.headline, 'Fuel & Free Time MCP wants to connect to ChatGPT');
+  assert.equal(view.copy.footer, 'Authorization secured by Fuel & Free Time');
+  assert.deepEqual(view.scopes.map((scope) => scope.scope), [
+    'fnf:experience.read',
+    'fnf:store.read',
+  ]);
+});
+
+test('OAuth consent rejects missing resource audience instead of inventing one', () => {
+  assert.throws(
+    () => buildOAuthConsentView({
+      company: { name: 'Example' },
+      resource: { display_name: 'Example MCP' },
+      client: { client_id: 'client', display_name: 'Client' },
+    }),
+    /oauth_consent_resource_audience_required/,
+  );
+});
+
+
+test('OAuth consent renderer escapes malicious strings in every dynamic field', () => {
+  const evil = '<script>alert(1)</script>"><img src=x onerror=alert(2)>';
+
+  const html = renderOAuthConsentHtml({
+    company: {
+      name: evil,
+      logo_url: 'javascript:alert(3)', // must be dropped (not http/https)
+      primary_color: 'red; } body { background: url(javascript:alert(4)) } .x {',
+    },
+    resource: {
+      audience: 'https://example.test/mcp',
+      display_name: evil,
+      description: evil,
+    },
+    client: {
+      client_id: 'evil-client',
+      display_name: evil,
+    },
+    signed_in_email: evil,
+    scopes: [
+      { scope: 's1', label: evil, description: evil },
+    ],
+  }, { authorizationId: evil, csrfToken: evil });
+
+  // Nothing from any dynamic field should survive as a live tag/attribute.
+  assert.ok(!html.includes('<script>'), 'raw <script> tag leaked unescaped');
+  assert.ok(!html.includes('<img src=x'), 'raw <img> tag leaked unescaped (would fire onerror as a live element)');
+  // The dangerous substring is fine to appear as INERT escaped text -- what matters
+  // is that it never appears as a live, browser-parsed tag (i.e. preceded by a raw '<').
+  assert.ok(!html.includes('javascript:alert'), 'javascript: URL was not rejected by safeHttpUrl');
+  assert.ok(!html.includes('background: url(javascript'), 'invalid color value leaked into <style> unescaped');
+
+  // The escaped form of the payload should be present wherever it was rendered.
+  const escaped = '&lt;script&gt;alert(1)&lt;/script&gt;&quot;&gt;&lt;img src=x onerror=alert(2)&gt;';
+  assert.ok(html.includes(escaped), 'expected HTML-escaped payload not found in output');
+
+  // Invalid color input must fall back to the safe default, not pass through raw.
+  assert.ok(html.includes('#171717') || html.includes('#0b1020'), 'expected safe fallback brand color not found');
+});

package/packages/identity/tests/oauth-credentials.test.mjs

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
+import { PLATFORM_ACCOUNT_ISSUER } from '../src/contracts/auth-config.js';
 import {
   requireIamPlatformCredentials,
   resolveIamPlatformCredentials,
@@ -7,11 +8,21 @@ import {
 } from '../src/oauth/credentials.js';
 
 describe('oauth credentials', () => {
-  it('requires IAM_CLIENT_ID and IAM_CLIENT_SECRET together', () => {
+  it('requires IAM client credentials and defaults the issuer to the platform authority', () => {
     assert.equal(resolveIamPlatformCredentials({ IAM_CLIENT_ID: 'x' }), null);
+    const defaults = resolveIamPlatformCredentials({
+      IAM_CLIENT_ID: 'x',
+      IAM_CLIENT_SECRET: 'y',
+    });
+    assert.equal(defaults?.clientId, 'x');
+    assert.equal(defaults?.issuer, PLATFORM_ACCOUNT_ISSUER);
     assert.equal(
-      resolveIamPlatformCredentials({ IAM_CLIENT_ID: 'x', IAM_CLIENT_SECRET: 'y' })?.clientId,
-      'x',
+      resolveIamPlatformCredentials({
+        IAM_CLIENT_ID: 'x',
+        IAM_CLIENT_SECRET: 'y',
+        IAM_OAUTH_ISSUER: 'https://iam.example.test',
+      })?.issuer,
+      'https://iam.example.test',
     );
   });
 
@@ -26,6 +37,7 @@ describe('oauth credentials', () => {
     const env = {
       IAM_CLIENT_ID: 'iam_dcr_legendary',
       IAM_CLIENT_SECRET: 'secret',
+      IAM_OAUTH_ISSUER: 'https://iam.example.test',
     };
     const lane = resolveOAuthCredentialLane(env, 'google');
     assert.equal(lane?.lane, 'iam_platform');
@@ -36,6 +48,7 @@ describe('oauth credentials', () => {
     const env = {
       IAM_CLIENT_ID: 'iam_dcr_legendary',
       IAM_CLIENT_SECRET: 'secret',
+      IAM_OAUTH_ISSUER: 'https://iam.example.test',
       GOOGLE_CLIENT_ID: 'google-byok',
       GOOGLE_CLIENT_SECRET: 'gsecret',
     };
@@ -63,7 +76,7 @@ describe('oauth credentials', () => {
     const creds = resolveIamPlatformCredentials({
       IAM_CLIENT_ID: 'c',
       IAM_CLIENT_SECRET: 's',
-      IAM_OAUTH_ISSUER: 'https://staging.inneranimalmedia.com/',
+      IAM_ORIGIN: 'https://staging.inneranimalmedia.com/',
     });
     assert.equal(creds?.origin, 'https://staging.inneranimalmedia.com');
   });

package/packages/identity/tests/oauth-presets-accounts-ssot.test.mjs

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { resolveOAuthCredentialLane } from '../src/oauth/credentials.js';
+import { resolveGoogleExchangeSecret } from '../src/oauth/google-desktop-exchange.js';
+import { IdentityProviders } from '../src/contracts/provider.js';
+import { loadIdentityProviders, normalizeProviderTemplateId } from '../../../src/features/resolve.js';
+
+const PKG = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const MIGRATION = path.join(PKG, 'src/migrations/0001_identity_core.sql');
+
+describe('identity OAuth presets + accounts SSOT', () => {
+  it('migration declares accounts as SSOT before account_identities', () => {
+    const sql = fs.readFileSync(MIGRATION, 'utf8');
+    assert.match(sql, /CREATE TABLE IF NOT EXISTS accounts/);
+    assert.match(sql, /account_identities[`']?\s+is IdP linkage only/i);
+    assert.match(sql, /never the account SSOT/i);
+    const accountsAt = sql.indexOf('CREATE TABLE IF NOT EXISTS accounts');
+    const identitiesAt = sql.indexOf('CREATE TABLE IF NOT EXISTS account_identities');
+    assert.ok(accountsAt >= 0 && identitiesAt > accountsAt);
+  });
+
+  it('provider catalog includes google_desktop + cloudflare', () => {
+    const providers = loadIdentityProviders();
+    const ids = providers.map((p) => p.id);
+    assert.ok(ids.includes('google_desktop'));
+    assert.ok(ids.includes('cloudflare'));
+    assert.ok(IdentityProviders.includes('google_desktop'));
+    assert.equal(normalizeProviderTemplateId('google-desktop'), 'google_desktop');
+  });
+
+  it('resolves google_desktop and cloudflare credential lanes', () => {
+    const desktop = resolveOAuthCredentialLane(
+      { GOOGLE_DESKTOP_CLIENT_ID: 'desk.apps.googleusercontent.com' },
+      'google_desktop',
+    );
+    assert.equal(desktop?.lane, 'byok_google_desktop');
+    assert.equal(desktop?.provider, 'google_desktop');
+
+    const cf = resolveOAuthCredentialLane(
+      { CLOUDFLARE_OAUTH_CLIENT_ID: 'cf-client' },
+      'cloudflare',
+    );
+    assert.equal(cf?.lane, 'byok_cloudflare');
+    assert.equal(cf?.clientSecret, '');
+  });
+
+  it('desktop exchange secret resolution prefers public PKCE', () => {
+    const resolved = resolveGoogleExchangeSecret(
+      { GOOGLE_DESKTOP_CLIENT_ID: 'desk.apps.googleusercontent.com' },
+      'desk.apps.googleusercontent.com',
+    );
+    assert.equal(resolved.mode, 'desktop_public_pkce');
+    assert.equal(resolved.clientSecret, null);
+  });
+});

package/packages/identity/tests/preview-auth-portal.test.mjs

@@ -13,7 +13,7 @@ describe('auth portal preview server', () => {
     }
   });
 
-  it('serves IAM auth paths and login HTML', async () => {
+  it('serves portable auth paths and login HTML', async () => {
     const started = await createAuthPortalPreviewServer({ port: 0, host: '127.0.0.1' });
     server = started.server;
     baseUrl = started.baseUrl;
@@ -21,7 +21,7 @@ describe('auth portal preview server', () => {
     const loginRes = await fetch(`${baseUrl}/auth/login`);
     assert.equal(loginRes.status, 200);
     const loginHtml = await loginRes.text();
-    assert.match(loginHtml, /Sign in \| Inner Animal Media/);
+    assert.match(loginHtml, /Sign in \| AgentSam/);
 
     const signupRes = await fetch(`${baseUrl}/auth/signup`);
     assert.equal(signupRes.status, 200);
@@ -34,7 +34,7 @@ describe('auth portal preview server', () => {
     const companyRes = await fetch(`${baseUrl}/api/company`);
     const companyJson = await companyRes.json();
     assert.equal(companyJson.ok, true);
-    assert.equal(companyJson.company.supportEmail, 'hey@inneranimalmedia.com');
+    assert.equal(companyJson.company.supportEmail, 'support@agentsam.dev');
 
     const apiRes = await fetch(`${baseUrl}/api/auth/login`, {
       method: 'POST',

package/packages/runtime-protocol/src/index.js

@@ -0,0 +1,154 @@
+/**
+ * agentsam.runtime.v1 — Runtime Registry vocabulary (JS).
+ * Physical D1 tables remain terminal_* ; domain nouns are Runtime*.
+ * Schema SSOT: protocol/runtime/agentsam.runtime.v1.schema.json
+ * Law: docs/architecture/AGENTSAM_RUNTIME_PROTOCOL.md
+ */
+
+export const RUNTIME_PROTOCOL_SCHEMA = 'agentsam.runtime.v1';
+
+/** Compute owner / cloud. Application-validated (no aggressive D1 CHECK). */
+export const RUNTIME_PROVIDERS = Object.freeze([
+  'local',
+  'google_cloud',
+  'cloudflare',
+  'aws',
+  'azure',
+  'fly',
+  'custom',
+]);
+
+/** What kind of computer/environment. */
+export const RUNTIME_SUBSTRATES = Object.freeze([
+  'host',
+  'vm',
+  'container',
+  'sandbox',
+  'workstation',
+  'microvm',
+  'kubernetes',
+]);
+
+export const RUNTIME_LIFECYCLES = Object.freeze([
+  'persistent',
+  'scale_to_zero',
+  'ephemeral',
+  'job',
+]);
+
+/**
+ * What speaks agentsam.runtime.v1 on the instance.
+ * ExecOS is an adapter implementation — never a transport.
+ */
+export const RUNTIME_ADAPTERS = Object.freeze([
+  'agentsamd',
+  'execos_legacy',
+  'cloudflare_sandbox',
+  'docker_engine',
+  'ssh',
+  'provider_native',
+]);
+
+/** How Studio/IAM reaches the adapter. */
+export const RUNTIME_TRANSPORTS = Object.freeze([
+  'direct_https',
+  'direct_wss',
+  'cloudflare_tunnel',
+  'vpc_service',
+  'vpc_network',
+  'service_binding',
+  'local_socket',
+  'provider_api',
+  'ssh',
+]);
+
+export const RUNTIME_AUTH_MODES = Object.freeze([
+  'connection_token',
+  'platform_bridge',
+  'bridge_key',
+  'service_binding',
+]);
+
+/** Capability keys — discovered, never inferred from provider alone. */
+export const RUNTIME_CAPABILITY_KEYS = Object.freeze([
+  'exec',
+  'pty',
+  'filesystem',
+  'persistent_filesystem',
+  'process',
+  'git',
+  'docker',
+  'gpu',
+  'browser',
+  'gui',
+  'ports',
+  'snapshot',
+]);
+
+/** @deprecated use RUNTIME_ADAPTERS */
+export const RUNTIME_KINDS = RUNTIME_ADAPTERS;
+
+/**
+ * Map legacy terminal_instances.kind → substrate.
+ * @param {'local_device'|'vm'|'sandbox'|string} kind
+ */
+export function substrateFromLegacyKind(kind) {
+  const k = String(kind || '').trim().toLowerCase();
+  if (k === 'local_device') return { substrate: 'host', target_lane: 'local', provider_hint: 'local' };
+  if (k === 'vm') return { substrate: 'vm', target_lane: 'remote', provider_hint: 'google_cloud' };
+  if (k === 'sandbox') return { substrate: 'sandbox', target_lane: 'sandbox', provider_hint: 'cloudflare' };
+  return { substrate: null, target_lane: null, provider_hint: null };
+}
+
+/**
+ * Map legacy connection transport + transport_provider → adapter + transport.
+ * @param {{ transport?: string, transport_provider?: string }} row
+ */
+export function normalizeLegacyConnection(row = {}) {
+  const legacyTransport = String(row.transport || '').trim().toLowerCase();
+  const legacyProvider = String(row.transport_provider || '').trim().toLowerCase();
+  let runtime_adapter = 'agentsamd';
+  if (legacyTransport === 'execos') runtime_adapter = 'execos_legacy';
+  else if (legacyTransport === 'container') runtime_adapter = 'cloudflare_sandbox';
+
+  let transport = legacyProvider || null;
+  if (!transport || transport === 'platform_vpc') {
+    transport = transport === 'platform_vpc' ? 'vpc_service' : 'direct_https';
+  }
+  if (legacyTransport === 'container' && !legacyProvider) {
+    transport = 'service_binding';
+  }
+
+  return {
+    protocol: RUNTIME_PROTOCOL_SCHEMA,
+    runtime_adapter,
+    transport,
+  };
+}
+
+/**
+ * Normalize arch vocabulary (live GCP still has x64).
+ * @param {string|null|undefined} arch
+ */
+export function normalizeArch(arch) {
+  const a = String(arch || '').trim().toLowerCase();
+  if (!a) return null;
+  if (a === 'x64' || a === 'amd64' || a === 'x86_64') return 'x86_64';
+  if (a === 'arm64' || a === 'aarch64') return 'arm64';
+  return a;
+}
+
+/**
+ * Hard-constraint check: every required capability must be true on candidate.
+ * @param {Record<string, boolean>} required
+ * @param {Record<string, boolean>} available
+ * @returns {{ ok: boolean, missing: string[] }}
+ */
+export function capabilitiesSatisfy(required = {}, available = {}) {
+  const missing = [];
+  for (const [key, need] of Object.entries(required)) {
+    if (!need) continue;
+    if (available[key] !== true) missing.push(key);
+  }
+  return { ok: missing.length === 0, missing };
+}

package/packages/theme-scenes/README.md

@@ -0,0 +1,164 @@
+# @inneranimalmedia/theme-scenes
+
+Reusable **scene / shell / block** vocabulary for branded website experiences.
+
+| Layer | Owns |
+| --- | --- |
+| `@inneranimalmedia/agentsam-sdk-brand` | BrandPack — assets, tokens, roles, delivery |
+| **`@inneranimalmedia/theme-scenes`** | How brands compose into experiences |
+| Page content | What this page says/shows |
+| Demo adapters | Real product surfaces inside scenes |
+
+Scenes never hardcode CDN URLs, nav hrefs, or product copy. They consume `SECTION_CONTENT`, route refs, and asset roles.
+
+## Install
+
+Workspace package (private for now):
+
+```js
+import {
+  createWorkPreset,
+  compilePage,
+  createCopyBlock,
+  createActionBlock,
+  composeCardCollection,
+} from '@inneranimalmedia/theme-scenes';
+```
+
+## Hierarchy
+
+```
+PAGE_CONTENT
+  └── SECTION_CONTENT[]   → scene kind + theme + scroll + motion
+        └── SECTION_GROUP[]
+              └── CONTENT_BLOCK[]   copy | media | action | cards | demo | …
+```
+
+## Scene kinds (harvested from Work/Create HTML)
+
+| Former HTML piece | Scene / shell |
+| --- | --- |
+| Sticky glass headers | `shell.adaptive-header` |
+| Dark / light globe heroes | `hero.scroll-product` / `hero.editorial` + `visual.orbital-field` |
+| Light→dark gradient | `bridge.theme` |
+| Brand storyboard lanes | `gallery.storyboard` |
+| Icon marquee | `gallery.rail` (loop is one *behavior*) |
+| Service bento | `capability.grid` |
+| MeauxIDE mock | `product.demo` + `agentsam-mini-composer` |
+| MeauxSQL card | `product.demo` + `database-editor` |
+| Staggered tools | `product.stack` |
+| Chess / 3D stage | `interactive.stage` |
+| Footers | `shell.site-footer` |
+
+See `SCENE_ORIGIN` in `src/scenes/index.js`.
+
+## Laws
+
+1. No raw colors in scene contracts — use theme tokens / CSS vars.
+2. No hardcoded internal URLs — use `{ type: 'route', ref: '…' }`.
+3. No direct CDN URLs — use `{ assetRole: '…' }` + BrandPack resolver.
+4. No product copy inside generic scenes — inject via groups/blocks.
+5. No required card counts — empty collections disappear; adaptive layout.
+6. Major media slots support image / video / model / demo.
+7. Animated scenes declare reduced-motion behavior.
+8. Scenes declare theme intent (`surface`, `headerTone`, …).
+9. Product marketing uses real DemoAdapters, not fake UIs.
+10. Motion must communicate something (story/scrub), not decorate forever.
+
+## Quick example
+
+```js
+import {
+  createWorkPreset,
+  createCopyBlock,
+  createActionBlock,
+  createDemoBlock,
+  composeCardCollection,
+  compilePage,
+} from '@inneranimalmedia/theme-scenes';
+
+const page = createWorkPreset({
+  theme: 'inneranimal',
+  heroGroups: [{
+    blocks: [
+      createCopyBlock({
+        variant: 'display',
+        eyebrow: 'Selected Work',
+        title: 'Interface clarity.\nSystem discipline.',
+        body: 'Digital products with refined UI and production-grade foundations.',
+      }),
+      createActionBlock({
+        label: 'View the system',
+        target: { type: 'route', ref: 'product.agentsam' },
+      }),
+    ],
+  }],
+  agentsamGroups: [{
+    blocks: [
+      createCopyBlock({ title: 'AgentSam', body: 'Unified workspace shell.' }),
+      createDemoBlock('agentsam-mini-composer'),
+    ],
+  }],
+  productGroups: [{
+    blocks: [
+      composeCardCollection([
+        { title: 'Database', body: '…', target: { type: 'route', ref: 'product.database' } },
+        { title: 'Cloud', body: '…', target: { type: 'route', ref: 'product.cloud' } },
+      ]),
+    ],
+  }],
+});
+
+const plan = compilePage(page);
+// plan.sections[].demoHost, plan.cssVars, plan.validation
+```
+
+## Presets
+
+- `agency-home` — institutional flagship narrative  
+- `work` — Work page (dark or canvas hero via `heroTone`)  
+- `product` — single product landing  
+- `services` — capability grid  
+- `brand-story` — Create/guideline storyboard  
+
+```js
+import { createPreset, listPresets } from '@inneranimalmedia/theme-scenes';
+```
+
+## Themes
+
+`foundation` → `inneranimal` → `agentsam` / `autodidact`
+
+Semantic tokens only (`color.surface.canvas`, `type.display.xl`, …). `themeToCssVars()` emits `--scene-*` for hosts.
+
+## Scroll presets
+
+| Mode | Typical | Purpose |
+| --- | --- | --- |
+| `natural` | content height | ordinary |
+| `viewport` | ~100vh | focused statement |
+| `linger` | 120–160vh | visual + copy |
+| `sticky-story` | 180–260vh | narrative scrub |
+| `cinematic` | 240–320vh | flagship product |
+| `bridge` | 40–80vh | world transition |
+
+Hosts receive normalized `progress` 0→1 (`computeScrollProgress` / `stageAtProgress`).
+
+## Demo adapters
+
+| Adapter | Product surface |
+| --- | --- |
+| `agentsam-mini-composer` | AgentSam / MiniComposer |
+| `database-editor` | MeauxSQL-class DB editor |
+| `cad-viewer` | GLB turntable |
+| `generic-iframe` | last-resort embed |
+
+## Studio (next)
+
+Reusable `studio-shell` (navigator / canvas / inspector) sits *above* this package. Moon Glass mock → Brand Studio panels over BrandPack + theme-scenes — not another one-off HTML page. See AgentSam BrandPack README for the compiler side.
+
+## Tests
+
+```bash
+npm --prefix packages/theme-scenes test
+```

package/packages/theme-scenes/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@inneranimalmedia/theme-scenes",
+  "version": "0.1.0",
+  "description": "Reusable scene / shell / block vocabulary for branded website experiences. BrandPack owns look; theme-scenes owns composition.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22 <25"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./contracts": "./src/contracts/index.js",
+    "./scenes": "./src/scenes/index.js",
+    "./shell": "./src/shell/index.js",
+    "./blocks": "./src/blocks/index.js",
+    "./visuals": "./src/visuals/index.js",
+    "./demos": "./src/demos/index.js",
+    "./themes": "./src/themes/index.js",
+    "./presets": "./src/presets/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "packages/theme-scenes"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "keywords": [
+    "agentsam",
+    "theme",
+    "scenes",
+    "sections",
+    "brand",
+    "cms"
+  ],
+  "agentsam": {
+    "kind": "theme-runtime",
+    "slug": "theme-scenes",
+    "depends_on": [
+      "@inneranimalmedia/agentsam-sdk-brand"
+    ]
+  }
+}

package/packages/theme-scenes/src/blocks/index.js

@@ -0,0 +1,30 @@
+/**
+ * Block helpers — scenes compose these; they never own brand URLs.
+ */
+
+export {
+  createCopyBlock,
+  createMediaBlock,
+  createActionBlock,
+  createCardsBlock,
+  createDemoBlock,
+  composeCardCollection,
+  BLOCK_KINDS,
+} from '../contracts/index.js';
+
+/** Resolve whether a block should render (empty collections disappear). */
+export function shouldRenderBlock(block) {
+  if (!block?.kind) return false;
+  if (block.kind === 'cards') return Array.isArray(block.items) && block.items.length > 0;
+  if (block.kind === 'copy') {
+    return Boolean(block.title || block.body || block.eyebrow || (block.bullets && block.bullets.length));
+  }
+  if (block.kind === 'action') return Boolean(block.label);
+  if (block.kind === 'demo') return Boolean(block.adapter);
+  if (block.kind === 'media') return Boolean(block.media?.assetRole || block.media?.ref);
+  return true;
+}
+
+export function filterRenderableBlocks(blocks = []) {
+  return blocks.filter(shouldRenderBlock);
+}