@topogram/cli 0.3.34

package/src/generator/surfaces/web/shared.js

@@ -0,0 +1,369 @@
+function authTokenExpression(target) {
+  return target === "sveltekit"
+    ? 'publicEnv.PUBLIC_TOPOGRAM_AUTH_TOKEN || ""'
+    : 'readPublicEnv("PUBLIC_TOPOGRAM_AUTH_TOKEN") || readPublicEnv("VITE_PUBLIC_TOPOGRAM_AUTH_TOKEN")';
+}
+
+function apiBaseExpression(target, defaultApiBaseUrl) {
+  return target === "sveltekit"
+    ? `publicEnv.PUBLIC_TOPOGRAM_API_BASE_URL || "${defaultApiBaseUrl}"`
+    : `readPublicEnv("PUBLIC_TOPOGRAM_API_BASE_URL") || readPublicEnv("VITE_PUBLIC_TOPOGRAM_API_BASE_URL") || "${defaultApiBaseUrl}"`;
+}
+
+function publicEnvPreamble(target) {
+  return target === "sveltekit"
+    ? 'import { env as publicEnv } from "$env/dynamic/public";\n'
+    : "";
+}
+
+function publicEnvHelper(target) {
+  if (target === "sveltekit") {
+    return "";
+  }
+  return `function readPublicEnv(name: string) {
+  return import.meta.env[name] || "";
+}
+
+`;
+}
+
+export function renderVisibilityModule(target) {
+  const preamble = target === "sveltekit" ? `${publicEnvPreamble(target)}\n` : publicEnvPreamble(target);
+  return `${preamble}export interface VisibilityRule {
+  predicate?: string | null;
+  value?: string | null;
+  claimValue?: string | null;
+  ownershipField?: string | null;
+  capability?: { id?: string | null } | null;
+}
+
+export interface VisibilityPrincipalOverride {
+  userId?: string | null;
+  permissions?: string | string[] | null;
+  roles?: string | string[] | null;
+  claims?: Record<string, unknown> | null;
+  isAdmin?: boolean | string | null;
+}
+
+interface AuthPrincipal {
+  userId: string;
+  permissions: Set<string>;
+  roles: Set<string>;
+  claims: Record<string, unknown>;
+  isAdmin: boolean;
+}
+
+${publicEnvHelper(target)}function authToken() {
+  return ${authTokenExpression(target)};
+}
+
+function csvValues(value: string) {
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function normalizeOverrideList(value: string | string[] | null | undefined) {
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0);
+  }
+  if (typeof value === "string") {
+    return csvValues(value);
+  }
+  return [];
+}
+
+function readBoolean(value: string) {
+  return value === "true" || value === "1" || value === "yes";
+}
+
+function parseClaimsJson(raw: string) {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
+  } catch {
+    return {};
+  }
+}
+
+function decodeJwtPayload(token: string) {
+  const parts = token.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const normalized = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), "=");
+    return JSON.parse(atob(padded));
+  } catch {
+    return null;
+  }
+}
+
+function principalFromJwt(token: string): AuthPrincipal | null {
+  const payload = decodeJwtPayload(token);
+  if (!payload || typeof payload !== "object") return null;
+  return {
+    userId: typeof payload.sub === "string" ? payload.sub : "",
+    permissions: new Set(Array.isArray(payload.permissions) ? payload.permissions.filter((value: unknown): value is string => typeof value === "string") : []),
+    roles: new Set(Array.isArray(payload.roles) ? payload.roles.filter((value: unknown): value is string => typeof value === "string") : []),
+    claims: payload as Record<string, unknown>,
+    isAdmin: payload.admin === true
+  };
+}
+
+function currentPrincipal(overrides?: VisibilityPrincipalOverride | null): AuthPrincipal | null {
+  const token = authToken();
+  const jwtPrincipal = token ? principalFromJwt(token) : null;
+  const envClaims = parseClaimsJson(${target === "sveltekit" ? 'publicEnv.PUBLIC_TOPOGRAM_AUTH_CLAIMS || ""' : 'readPublicEnv("PUBLIC_TOPOGRAM_AUTH_CLAIMS")'});
+  const userId = overrides?.userId || ${target === "sveltekit" ? "publicEnv.PUBLIC_TOPOGRAM_AUTH_USER_ID" : 'readPublicEnv("PUBLIC_TOPOGRAM_AUTH_USER_ID")'} || jwtPrincipal?.userId || "";
+  const permissions = new Set([
+    ...normalizeOverrideList(overrides?.permissions),
+    ...csvValues(${target === "sveltekit" ? 'publicEnv.PUBLIC_TOPOGRAM_AUTH_PERMISSIONS || ""' : 'readPublicEnv("PUBLIC_TOPOGRAM_AUTH_PERMISSIONS")'}),
+    ...Array.from(jwtPrincipal?.permissions || [])
+  ]);
+  const roles = new Set([
+    ...normalizeOverrideList(overrides?.roles),
+    ...csvValues(${target === "sveltekit" ? 'publicEnv.PUBLIC_TOPOGRAM_AUTH_ROLES || publicEnv.PUBLIC_TOPOGRAM_AUTH_ROLE || ""' : 'readPublicEnv("PUBLIC_TOPOGRAM_AUTH_ROLES") || readPublicEnv("PUBLIC_TOPOGRAM_AUTH_ROLE")'}),
+    ...Array.from(jwtPrincipal?.roles || [])
+  ]);
+  const isAdmin = (
+    typeof overrides?.isAdmin === "boolean"
+      ? overrides.isAdmin
+      : readBoolean(String(overrides?.isAdmin || ""))
+  ) || readBoolean(${target === "sveltekit" ? 'publicEnv.PUBLIC_TOPOGRAM_AUTH_ADMIN || ""' : 'readPublicEnv("PUBLIC_TOPOGRAM_AUTH_ADMIN")'}) || jwtPrincipal?.isAdmin === true;
+
+  const claims = {
+    ...(jwtPrincipal?.claims || {}),
+    ...envClaims,
+    ...(overrides?.claims || {})
+  };
+
+  if (!token && !userId && permissions.size === 0 && roles.size === 0 && Object.keys(claims).length === 0 && !isAdmin) {
+    return null;
+  }
+
+  return { userId, permissions, roles, claims, isAdmin };
+}
+
+function claimMatches(principal: AuthPrincipal, claim: string | null | undefined, claimValue: string | null | undefined) {
+  if (!claim) return true;
+  const value = principal.claims[claim];
+  if (value == null) return false;
+  if (!claimValue) {
+    return value !== false && value !== "";
+  }
+  return String(value) === claimValue;
+}
+
+function ownerIdFromResource(resource: Record<string, unknown> | null | undefined, ownershipField?: string | null) {
+  if (!resource || typeof resource !== "object") {
+    return "";
+  }
+
+  if (ownershipField) {
+    const explicitValue = resource[ownershipField];
+    return typeof explicitValue === "string" ? explicitValue : "";
+  }
+
+  for (const field of ["owner_id", "assignee_id", "author_id", "user_id", "created_by_user_id"]) {
+    const value = resource[field];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+
+  return "";
+}
+
+export function canShowAction(
+  rule: VisibilityRule | null | undefined,
+  resource?: Record<string, unknown> | null,
+  overrides?: VisibilityPrincipalOverride | null
+) {
+  if (!rule) return true;
+
+  const principal = currentPrincipal(overrides);
+  if (!principal) {
+    return true;
+  }
+
+  if (rule.predicate === "permission") {
+    if (!rule.value) return true;
+    return principal.permissions.has("*") || principal.permissions.has(rule.value);
+  }
+
+  if (rule.predicate === "ownership") {
+    if (!rule.value || rule.value === "none") return true;
+    if (rule.value === "owner_or_admin" && principal.isAdmin) return true;
+    return ownerIdFromResource(resource, rule.ownershipField) === principal.userId;
+  }
+
+  if (rule.predicate === "claim") {
+    return claimMatches(principal, rule.value, rule.claimValue);
+  }
+
+  return true;
+}
+`;
+}
+
+export function renderApiClientModule(target, webReference, options = {}) {
+  const defaultApiBaseUrl = webReference.defaultApiBaseUrl || "http://localhost:3000";
+  const supportsDownload = Boolean(options.supportsDownload);
+  const contractsImportPath = target === "sveltekit" ? "$lib/topogram/api-contracts.json" : "../topogram/api-contracts.json";
+  return `${publicEnvPreamble(target)}import apiContracts from "${contractsImportPath}";
+
+type Fetcher = typeof fetch;
+type ApiContract = (typeof apiContracts)[keyof typeof apiContracts];
+type RequestOptions = {
+  headers?: Record<string, string>;
+};
+
+${target === "react" ? "" : publicEnvHelper(target)}function apiBase() {
+  return ${target === "react"
+    ? `import.meta.env.PUBLIC_TOPOGRAM_API_BASE_URL || import.meta.env.VITE_PUBLIC_TOPOGRAM_API_BASE_URL || "${defaultApiBaseUrl}"`
+    : apiBaseExpression(target, defaultApiBaseUrl)};
+}
+
+function authToken() {
+  return ${target === "react"
+    ? 'import.meta.env.PUBLIC_TOPOGRAM_AUTH_TOKEN || import.meta.env.VITE_PUBLIC_TOPOGRAM_AUTH_TOKEN || ""'
+    : authTokenExpression(target)};
+}
+
+function buildPath(contract: ApiContract, input: Record<string, unknown>) {
+  let path = contract.endpoint.path;
+  for (const field of contract.requestContract?.transport.path || []) {
+    const raw = input[field.name];
+    path = path.replace(\`:\${field.transport.wireName}\`, encodeURIComponent(String(raw ?? "")));
+  }
+  const params = new URLSearchParams();
+  for (const field of contract.requestContract?.transport.query || []) {
+    const raw = input[field.name];
+    if (raw !== undefined && raw !== null && raw !== "") {
+      params.set(field.transport.wireName, String(raw));
+    }
+  }
+  const query = params.toString();
+  return query ? \`\${path}?\${query}\` : path;
+}
+
+export async function requestCapability(fetcher: Fetcher, capabilityId: keyof typeof apiContracts, input: Record<string, unknown> = {}, options: RequestOptions = {}) {
+  const contract = apiContracts[capabilityId];
+  const url = new URL(buildPath(contract, input), apiBase()).toString();
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(options.headers || {})) {
+    headers.set(name, value);
+  }
+  if ((contract.endpoint.authz || []).length > 0 && authToken() && !headers.has("Authorization")) {
+    headers.set("Authorization", "Bearer " + authToken());
+  }
+  let body: string | undefined;
+  if ((contract.requestContract?.transport.body || []).length > 0) {
+    headers.set("content-type", "application/json");
+    const payload: Record<string, unknown> = {};
+    for (const field of contract.requestContract?.transport.body || []) {
+      if (input[field.name] !== undefined) {
+        payload[field.transport.wireName] = input[field.name];
+      }
+    }
+    body = JSON.stringify(payload);
+  }
+  const response = await fetcher(url, { method: contract.endpoint.method, headers, body });
+  if (!response.ok) {
+    const detail = await response.text();
+    const error = new Error(\`\${contract.endpoint.method} \${contract.endpoint.path} failed (\${response.status}): \${detail}\`) as Error & { status?: number; detail?: string };
+    error.status = response.status;
+    error.detail = detail;
+    throw error;
+  }
+  if (response.status === 204) {
+    return null;
+  }
+  ${supportsDownload ? 'if ((contract.endpoint.download || []).length > 0) {\n    return response.arrayBuffer();\n  }\n  ' : ""}return response.json();
+}
+
+export async function listPrimaryResources(fetcher: Fetcher, input: Record<string, unknown> = {}) {
+  return requestCapability(fetcher, "${webReference.client.capabilityIds.list}", input);
+}
+export async function ${webReference.client.functionNames.list}(fetcher: Fetcher, input: Record<string, unknown> = {}) {
+  return listPrimaryResources(fetcher, input);
+}
+
+export async function getPrimaryResource(fetcher: Fetcher, primary_id: string) {
+  return requestCapability(fetcher, "${webReference.client.capabilityIds.get}", { ${webReference.client.primaryParam}: primary_id });
+}
+export async function ${webReference.client.functionNames.get}(fetcher: Fetcher, primary_id: string) {
+  return getPrimaryResource(fetcher, primary_id);
+}
+
+export async function createPrimaryResource(fetcher: Fetcher, input: Record<string, unknown>, options: RequestOptions = {}) {
+  return requestCapability(fetcher, "${webReference.client.capabilityIds.create}", input, options);
+}
+export async function ${webReference.client.functionNames.create}(fetcher: Fetcher, input: Record<string, unknown>, options: RequestOptions = {}) {
+  return createPrimaryResource(fetcher, input, options);
+}
+
+export async function updatePrimaryResource(fetcher: Fetcher, primary_id: string, input: Record<string, unknown> = {}, options: RequestOptions = {}) {
+  return requestCapability(fetcher, "${webReference.client.capabilityIds.update}", { ${webReference.client.primaryParam}: primary_id, ...input }, options);
+}
+export async function ${webReference.client.functionNames.update}(fetcher: Fetcher, primary_id: string, input: Record<string, unknown> = {}, options: RequestOptions = {}) {
+  return updatePrimaryResource(fetcher, primary_id, input, options);
+}
+
+export async function terminalPrimaryAction(fetcher: Fetcher, primary_id: string, input: Record<string, unknown> = {}, options: RequestOptions = {}) {
+  return requestCapability(fetcher, "${webReference.client.capabilityIds.terminal}", { ${webReference.client.primaryParam}: primary_id, ...input }, options);
+}
+export async function ${webReference.client.functionNames.terminal}(fetcher: Fetcher, primary_id: string, input: Record<string, unknown> = {}, options: RequestOptions = {}) {
+  return terminalPrimaryAction(fetcher, primary_id, input, options);
+}
+${(webReference.client.extraFunctions || []).map((entry) => {
+  const params = entry.primaryParam
+    ? `fetcher: Fetcher, ${entry.primaryParam}: string, input: Record<string, unknown> = {}, options: RequestOptions = {}`
+    : "fetcher: Fetcher, input: Record<string, unknown> = {}, options: RequestOptions = {}";
+  const payload = entry.primaryParam
+    ? `{ ${entry.primaryParam}, ...input }`
+    : "input";
+  return `
+export async function ${entry.name}(${params}) {
+  return requestCapability(fetcher, "${entry.capabilityId}", ${payload}, options);
+}`;
+}).join("\n")}
+`;
+}
+
+export function renderLookupModule(target, defaultApiBaseUrl) {
+  const preamble = target === "sveltekit" ? `${publicEnvPreamble(target)}\n` : publicEnvPreamble(target);
+  const authTokenHelper = `function authToken() {
+  return ${target === "react"
+    ? 'import.meta.env.PUBLIC_TOPOGRAM_AUTH_TOKEN || import.meta.env.VITE_PUBLIC_TOPOGRAM_AUTH_TOKEN || ""'
+    : authTokenExpression(target)};
+}
+
+`;
+  return `${preamble}export interface LookupOption {
+  value: string;
+  label: string;
+}
+
+${target === "react" ? "" : publicEnvHelper(target)}function apiBase() {
+  return ${target === "react"
+    ? `import.meta.env.PUBLIC_TOPOGRAM_API_BASE_URL || import.meta.env.VITE_PUBLIC_TOPOGRAM_API_BASE_URL || "${defaultApiBaseUrl}"`
+    : apiBaseExpression(target, defaultApiBaseUrl)};
+}
+
+${authTokenHelper}export async function listLookupOptions(fetcher: typeof fetch, route: string): Promise<LookupOption[]> {
+  const headers = new Headers();
+  if (authToken()) {
+    headers.set("Authorization", "Bearer " + authToken());
+  }
+  const response = await fetcher(new URL(route, apiBase()).toString(), { headers });
+  if (!response.ok) {
+    const detail = await response.text();
+    throw new Error(\`Lookup request failed (\${response.status}): \${detail}\`);
+  }
+  return response.json();
+}
+`;
+}

package/src/generator/surfaces/web/sveltekit-actions.js

@@ -0,0 +1,28 @@
+function indentBlock(block, spaces) {
+  const indent = " ".repeat(spaces);
+  return block
+    .trim()
+    .split("\n")
+    .map((line) => (line ? `${indent}${line}` : ""))
+    .join("\n");
+}
+
+export function renderSvelteKitRedirectingAction({
+  actionName,
+  signature,
+  prelude,
+  tryStatement,
+  catchReturn,
+  successStatement
+}) {
+  return `  ${actionName}: async (${signature}) => {
+${indentBlock(prelude, 4)}
+
+    try {
+${indentBlock(tryStatement, 6)}
+    } catch (error) {
+${indentBlock(catchReturn, 6)}
+    }
+    ${successStatement}
+  }`;
+}

package/src/generator/surfaces/web/sveltekit-components.js

@@ -0,0 +1,234 @@
+// @ts-check
+
+/**
+ * @typedef {{ id?: string, name?: string }} ComponentReference
+ * @typedef {{ component?: ComponentReference, region?: string }} ComponentUsage
+ * @typedef {{ patterns?: string[] }} ComponentContract
+ * @typedef {Record<string, ComponentContract>} ComponentContractMap
+ * @typedef {{ itemsExpression?: string, componentContracts?: ComponentContractMap, useTypescript?: boolean }} RenderOptions
+ * @typedef {{ components?: ComponentUsage[] }} ScreenContract
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function escapeHtml(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @returns {string}
+ */
+function componentName(usage) {
+  return usage?.component?.name || usage?.component?.id || "Component";
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @returns {string}
+ */
+function componentId(usage) {
+  return usage?.component?.id || "component";
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {ComponentContractMap | undefined} componentContracts
+ * @returns {string[]}
+ */
+function componentPatterns(usage, componentContracts) {
+  const id = usage?.component?.id;
+  const contract = id ? componentContracts?.[id] : null;
+  return Array.isArray(contract?.patterns) ? contract.patterns : [];
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {ComponentContractMap | undefined} componentContracts
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+function hasPattern(usage, componentContracts, pattern) {
+  return componentPatterns(usage, componentContracts).includes(pattern);
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {RenderOptions} options
+ * @returns {string}
+ */
+function renderSummaryStats(usage, options) {
+  const items = options.itemsExpression || "data.result.items";
+  return `<section class="component-card component-summary" data-topogram-component="${escapeHtml(componentId(usage))}">
+          <div>
+            <p class="component-eyebrow">Component</p>
+            <h2>${escapeHtml(componentName(usage))}</h2>
+          </div>
+          <div class="summary-grid">
+            <div>
+              <strong>{${items}.length}</strong>
+              <span>Total</span>
+            </div>
+            <div>
+              <strong>{Object.keys(${items}[0] ?? {}).length}</strong>
+              <span>Fields</span>
+            </div>
+            <div>
+              <strong>{${items}.filter((item) => item && (item.id ?? item.uuid ?? item.key)).length}</strong>
+              <span>Identified</span>
+            </div>
+          </div>
+        </section>`;
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {RenderOptions} options
+ * @returns {string}
+ */
+function renderCollectionTable(usage, options) {
+  const items = options.itemsExpression || "data.result.items";
+  return `<div class="component-card component-table" data-topogram-component="${escapeHtml(componentId(usage))}">
+          <div class="component-header">
+            <div>
+              <p class="component-eyebrow">Component</p>
+              <h2>${escapeHtml(componentName(usage))}</h2>
+            </div>
+            <span class="badge">{${items}.length} items</span>
+          </div>
+          <div class="table-wrap component-table-wrap">
+            <table class="resource-table data-grid">
+              <thead>
+                <tr>
+                  {#each Object.keys(${items}[0] ?? {}).slice(0, 4) as field}
+                    <th>{field}</th>
+                  {/each}
+                </tr>
+              </thead>
+              <tbody>
+                {#each ${items} as item}
+                  <tr>
+                    {#each Object.keys(${items}[0] ?? {}).slice(0, 4) as field}
+                      <td>{String(item?.[field] ?? "")}</td>
+                    {/each}
+                  </tr>
+                {/each}
+              </tbody>
+            </table>
+          </div>
+        </div>`;
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {RenderOptions} options
+ * @returns {string}
+ */
+function renderBoard(usage, options) {
+  const items = options.itemsExpression || "data.result.items";
+  return `<div class="component-card component-board" data-topogram-component="${escapeHtml(componentId(usage))}">
+          <div class="component-header">
+            <div>
+              <p class="component-eyebrow">Component</p>
+              <h2>${escapeHtml(componentName(usage))}</h2>
+            </div>
+          </div>
+          <div class="board-grid">
+            {#each Array.from(new Set(${items}.map((item) => item?.status ?? item?.state ?? item?.stage ?? item?.category ?? "items"))) as group}
+              <section class="board-column">
+                <h3>{group}</h3>
+                {#each ${items}.filter((item) => (item?.status ?? item?.state ?? item?.stage ?? item?.category ?? "items") === group) as item}
+                  <div class="board-card">{item.title ?? item.name ?? item.label ?? item.message ?? item.id ?? JSON.stringify(item)}</div>
+                {/each}
+              </section>
+            {/each}
+          </div>
+        </div>`;
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {RenderOptions} options
+ * @returns {string}
+ */
+function renderCalendar(usage, options) {
+  const items = options.itemsExpression || "data.result.items";
+  return `<div class="component-card component-calendar" data-topogram-component="${escapeHtml(componentId(usage))}">
+          <div class="component-header">
+            <div>
+              <p class="component-eyebrow">Component</p>
+              <h2>${escapeHtml(componentName(usage))}</h2>
+            </div>
+          </div>
+          <div class="calendar-list">
+            {#each ${items}.filter((item) => item?.date || item?.due_at || item?.dueAt || item?.created_at || item?.createdAt || item?.updated_at || item?.updatedAt) as item}
+              <div class="calendar-card">
+                <span>{item.date ?? item.due_at ?? item.dueAt ?? item.created_at ?? item.createdAt ?? item.updated_at ?? item.updatedAt}</span>
+                <strong>{item.title ?? item.name ?? item.label ?? item.message ?? item.id ?? JSON.stringify(item)}</strong>
+              </div>
+            {/each}
+          </div>
+        </div>`;
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {RenderOptions} options
+ * @returns {string}
+ */
+function renderUsage(usage, options) {
+  const componentContracts = options.componentContracts || {};
+  if (hasPattern(usage, componentContracts, "summary_stats")) {
+    return renderSummaryStats(usage, options);
+  }
+  if (hasPattern(usage, componentContracts, "board_view")) {
+    return renderBoard(usage, options);
+  }
+  if (hasPattern(usage, componentContracts, "calendar_view")) {
+    return renderCalendar(usage, options);
+  }
+  if (hasPattern(usage, componentContracts, "resource_table") || hasPattern(usage, componentContracts, "data_grid_view")) {
+    return renderCollectionTable(usage, options);
+  }
+  return "";
+}
+
+/**
+ * @param {ScreenContract} screen
+ * @param {string} region
+ * @returns {ComponentUsage[]}
+ */
+export function svelteKitComponentUsagesForRegion(screen, region) {
+  return (screen?.components || []).filter((usage) => usage?.region === region);
+}
+
+/**
+ * @param {ScreenContract} screen
+ * @param {string} region
+ * @returns {boolean}
+ */
+export function hasSvelteKitComponentRegion(screen, region) {
+  return svelteKitComponentUsagesForRegion(screen, region).length > 0;
+}
+
+/**
+ * @param {ScreenContract} screen
+ * @param {string} region
+ * @param {RenderOptions} [options]
+ * @returns {string}
+ */
+export function renderSvelteKitComponentRegion(screen, region, options = {}) {
+  const rendered = svelteKitComponentUsagesForRegion(screen, region)
+    .map((usage) => renderUsage(usage, options))
+    .filter(Boolean);
+  if (rendered.length === 0) {
+    return "";
+  }
+  return rendered.join("\n");
+}