@texuli/blocks 0.0.0-stage → 0.1.0-next.0

package/dist/embed/EmbedApp.svelte

@@ -0,0 +1,138 @@
+<script lang="ts">
+import { onDestroy } from 'svelte';
+import type { EmbedBlockLabels, EmbedMountResult } from './family.js';
+import type { EmbedAppBlock } from './schema.js';
+
+interface Props {
+  block: EmbedAppBlock;
+  /**
+   * Host callback after Start. Texuli does not run `block.app`. Prefer
+   * `createSandboxedEmbedMount` from `@texuli/blocks/embed` for URL frames
+   * (sandbox without allow-same-origin, no-referrer, origin allowlist).
+   * Host must enforce CSP frame-src and postMessage origin checks.
+   */
+  mountEmbed?: (
+    target: HTMLElement,
+    app: Record<string, unknown>
+  ) => EmbedMountResult | Promise<EmbedMountResult>;
+  labels: EmbedBlockLabels;
+}
+
+let { block, mountEmbed, labels }: Props = $props();
+let started = $state(false);
+let pending = $state(false);
+let error = $state<string | null>(null);
+let mountEl = $state<HTMLDivElement | undefined>(undefined);
+let cleanup: (() => void) | undefined;
+let cancelled = false;
+
+$effect(() => {
+  const frame = mountEl;
+  if (!frame) return;
+  frame.addEventListener('keydown', onFrameKeydown);
+  return () => frame.removeEventListener('keydown', onFrameKeydown);
+});
+
+async function start() {
+  if (pending || started) return;
+  if (!mountEmbed || !mountEl) {
+    error = labels.unavailable;
+    return;
+  }
+  pending = true;
+  error = null;
+  cancelled = false;
+  try {
+    const dispose = await mountEmbed(mountEl, block.app);
+    if (cancelled) {
+      if (typeof dispose === 'function') dispose();
+      return;
+    }
+    if (typeof dispose === 'function') cleanup = dispose;
+    started = true;
+    mountEl.focus();
+  } catch {
+    if (!cancelled) error = labels.startError;
+  } finally {
+    if (!cancelled) pending = false;
+  }
+}
+
+function close() {
+  cancelled = true;
+  const dispose = cleanup;
+  cleanup = undefined;
+  try {
+    dispose?.();
+  } catch {
+    // Runtime cleanup must not disrupt its host document.
+  }
+  mountEl?.replaceChildren();
+  started = false;
+  pending = false;
+}
+
+function onFrameKeydown(event: KeyboardEvent) {
+  if (!started || event.key !== 'Tab' || !mountEl) return;
+  const focusable = [
+    ...mountEl.querySelectorAll<HTMLElement>(
+      'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+    ),
+  ].filter((element) => !element.hasAttribute('disabled') && element.tabIndex >= 0);
+  const first = focusable[0];
+  const last = focusable.at(-1);
+  if (!first || !last) {
+    event.preventDefault();
+    mountEl.focus();
+    return;
+  }
+  const active = document.activeElement;
+  if (event.shiftKey && (active === first || active === mountEl)) {
+    event.preventDefault();
+    last.focus();
+  } else if (!event.shiftKey && active === last) {
+    event.preventDefault();
+    first.focus();
+  }
+}
+
+onDestroy(close);
+</script>
+
+<section class="tx-embed-app" data-tx-block="embed-app" data-tx-embed-started={started} aria-label={block.title}>
+  <header class="tx-embed-header">
+    <h3>{block.title}</h3>
+    {#if started}<button type="button" onclick={close}>{labels.close}</button>{/if}
+  </header>
+  <div class="tx-embed-content" data-size={block.height ?? 'md'}>
+    {#if !started}
+      <div class="tx-embed-start">
+        <p>{labels.idle}</p>
+        <button type="button" disabled={pending} aria-busy={pending || undefined} onclick={start}>
+          {pending ? labels.starting : block.startLabel ?? labels.start}
+        </button>
+      </div>
+    {/if}
+    {#if error}<p role="alert">{error}</p>{/if}
+    <!-- Host runtime is deferred until the user activates the start button. -->
+    <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+    <div bind:this={mountEl} class="tx-embed-mount" hidden={!started} tabindex={started ? 0 : -1} role="region" aria-label={`${block.title} app`}></div>
+  </div>
+</section>
+
+<style>
+  .tx-embed-app { overflow: hidden; border: 1px solid var(--tx-color-border, #9ca3af); border-radius: 0.625rem; background: var(--tx-color-surface, Canvas); color: var(--tx-color-text, CanvasText); }
+  .tx-embed-header { display: flex; align-items: center; justify-content: space-between; gap: 0.75rem; padding: 0.75rem 1rem; border-block-end: 1px solid var(--tx-color-border, #9ca3af); }
+  .tx-embed-header h3 { margin: 0; font-size: 1rem; }
+  .tx-embed-content { min-block-size: 16rem; padding: 1rem; }
+  .tx-embed-content[data-size='sm'] { min-block-size: 10rem; }
+  .tx-embed-content[data-size='lg'] { min-block-size: 24rem; }
+  .tx-embed-start { display: grid; min-block-size: inherit; align-content: center; justify-items: center; gap: 0.75rem; text-align: center; }
+  .tx-embed-start p { margin: 0; }
+  button { min-block-size: 2.5rem; padding-inline: 1rem; border: 1px solid currentColor; border-radius: 0.375rem; background: var(--tx-color-accent, #4338ca); color: var(--tx-color-on-accent, white); font: inherit; cursor: pointer; }
+  button:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
+  button:disabled { cursor: wait; opacity: 0.65; }
+  .tx-embed-mount { min-block-size: 12rem; overflow: auto; }
+  [role='alert'] { color: var(--tx-color-danger, #b91c1c); }
+  @media (forced-colors: active) { .tx-embed-app, .tx-embed-header { border-color: CanvasText; } button { border: 1px solid ButtonText; } }
+</style>

package/dist/embed/EmbedApp.svelte.d.ts

@@ -0,0 +1,17 @@
+/// <reference path="../css-modules.d.ts" />
+import type { EmbedBlockLabels, EmbedMountResult } from './family.js';
+import type { EmbedAppBlock } from './schema.js';
+interface Props {
+    block: EmbedAppBlock;
+    /**
+     * Host callback after Start. Texuli does not run `block.app`. Prefer
+     * `createSandboxedEmbedMount` from `@texuli/blocks/embed` for URL frames
+     * (sandbox without allow-same-origin, no-referrer, origin allowlist).
+     * Host must enforce CSP frame-src and postMessage origin checks.
+     */
+    mountEmbed?: (target: HTMLElement, app: Record<string, unknown>) => EmbedMountResult | Promise<EmbedMountResult>;
+    labels: EmbedBlockLabels;
+}
+declare const EmbedApp: import("svelte").Component<Props, {}, "">;
+type EmbedApp = ReturnType<typeof EmbedApp>;
+export default EmbedApp;

package/dist/embed/EmbedBlockView.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+import EmbedApp from './EmbedApp.svelte';
+import type { EmbedBlockViewProps } from './family.js';
+import { DEFAULT_EMBED_BLOCK_LABELS } from './family.js';
+import LinkPreview from './LinkPreview.svelte';
+import { checkEmbedBlock } from './schema.js';
+
+let { block, mountEmbed, labels, oninvalid }: EmbedBlockViewProps = $props();
+const check = $derived(checkEmbedBlock(block));
+const text = $derived({ ...DEFAULT_EMBED_BLOCK_LABELS, ...labels });
+$effect(() => {
+  if (!check.ok) oninvalid?.(check.issues);
+});
+</script>
+
+{#if !check.ok}
+  <p class="tx-embed-invalid" data-tx-block="invalid" role="note">{text.invalid}</p>
+{:else if check.block.type === 'embed-app'}
+  <EmbedApp block={check.block} {mountEmbed} labels={text} />
+{:else}
+  <LinkPreview block={check.block} labels={text} />
+{/if}
+
+<style>
+  .tx-embed-invalid {
+    margin: 0;
+    padding: 0.625em 0.875em;
+    border: 1px dashed currentColor;
+    border-radius: 0.375em;
+    overflow-wrap: anywhere;
+  }
+</style>

package/dist/embed/EmbedBlockView.svelte.d.ts

@@ -0,0 +1,5 @@
+/// <reference path="../css-modules.d.ts" />
+import type { EmbedBlockViewProps } from './family.js';
+declare const EmbedBlockView: import("svelte").Component<EmbedBlockViewProps, {}, "">;
+type EmbedBlockView = ReturnType<typeof EmbedBlockView>;
+export default EmbedBlockView;

package/dist/embed/LinkPreview.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+import { safeHref } from '@texuli/core/url-policy';
+import type { EmbedBlockLabels } from './family.js';
+import type { LinkPreviewBlock } from './schema.js';
+
+interface Props {
+  block: LinkPreviewBlock;
+  labels: EmbedBlockLabels;
+}
+let { block, labels }: Props = $props();
+// Repeat the URL policy at the sink so this anchor remains safe if its caller changes.
+const href = $derived(safeHref(block.href, 'untrusted'));
+</script>
+
+<article class="tx-link-preview" data-tx-block="link-preview">
+  <div class="tx-link-copy">
+    {#if block.site}<p class="tx-link-site">{block.site}</p>{/if}
+    <h3>{block.title}</h3>
+    {#if block.description}<p>{block.description}</p>{/if}
+  </div>
+  {#if href}
+    <a href={href} target="_blank" rel="noopener noreferrer">{labels.link}<span class="tx-link-sr"> ({labels.newWindow})</span></a>
+  {/if}
+</article>
+
+<style>
+  .tx-link-preview { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 1rem; padding: 1rem; border: 1px solid var(--tx-color-border, #9ca3af); border-radius: 0.625rem; background: var(--tx-color-surface, Canvas); color: var(--tx-color-text, CanvasText); }
+  .tx-link-copy { min-inline-size: 0; }
+  h3, p { margin: 0; overflow-wrap: anywhere; }
+  h3 { font-size: 1rem; }
+  .tx-link-copy > p { margin-block-start: 0.375rem; }
+  /* Site line uses foreground (not muted) so WCAG AA holds on surface in light/dark/HC. */
+  .tx-link-site { color: var(--tx-color-text, CanvasText); font-size: 0.8125rem; }
+  a { color: var(--tx-color-link, LinkText); font-weight: 600; }
+  a:focus-visible { outline: 2px solid currentColor; outline-offset: 3px; }
+  .tx-link-sr { position: absolute; inline-size: 1px; block-size: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+  @media (forced-colors: active) {
+    .tx-link-preview {
+      background: Canvas;
+      color: CanvasText;
+      border-color: CanvasText;
+    }
+    .tx-link-site,
+    a {
+      color: LinkText;
+    }
+  }
+</style>

package/dist/embed/LinkPreview.svelte.d.ts

@@ -0,0 +1,10 @@
+/// <reference path="../css-modules.d.ts" />
+import type { EmbedBlockLabels } from './family.js';
+import type { LinkPreviewBlock } from './schema.js';
+interface Props {
+    block: LinkPreviewBlock;
+    labels: EmbedBlockLabels;
+}
+declare const LinkPreview: import("svelte").Component<Props, {}, "">;
+type LinkPreview = ReturnType<typeof LinkPreview>;
+export default LinkPreview;

package/dist/embed/engine.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@texuli/blocks/embed/engine` — Svelte-free embed sandbox helpers and parsers.
+ */
+import type { FieldIssue } from '../core/schema/primitives.js';
+import type { EmbedMountResult } from './sandbox.js';
+import type { EmbedAppBlock, LinkPreviewBlock } from './schema.js';
+export { type CreateSandboxedEmbedIframeOptions, createSandboxedEmbedIframe, createSandboxedEmbedMount, EMBED_IFRAME_REFERRER_POLICY, EMBED_IFRAME_SANDBOX, EMBED_IFRAME_SANDBOX_POPUPS_ESCAPE, type EmbedMountCleanup, type EmbedMountResult, embedIframeSandbox, type ResolveEmbedFrameSrcOptions, resolveEmbedFrameSrc, type SandboxedEmbedMountOptions, } from './sandbox.js';
+export type { EmbedAppBlock, EmbedBlock, EmbedBlockCheck, EmbedParseResult, LinkPreviewBlock, } from './schema.js';
+export { checkEmbedBlock, EMBED_APP_MAX_BYTES, safeParseEmbedBlock } from './schema.js';
+export declare const EMBED_BLOCK_TYPES: readonly ["embed-app", "link-preview"];
+export type EmbedFamilyBlockType = (typeof EMBED_BLOCK_TYPES)[number];
+export type EmbedFamilyBlock = EmbedAppBlock | LinkPreviewBlock;
+export interface EmbedBlockLabels {
+    invalid: string;
+    start: string;
+    starting: string;
+    close: string;
+    unavailable: string;
+    idle: string;
+    startError: string;
+    link: string;
+    newWindow: string;
+}
+export declare const DEFAULT_EMBED_BLOCK_LABELS: EmbedBlockLabels;
+export interface EmbedBlockViewProps {
+    block: unknown;
+    mountEmbed?: (target: HTMLElement, app: Record<string, unknown>) => EmbedMountResult | Promise<EmbedMountResult>;
+    labels?: Partial<EmbedBlockLabels>;
+    oninvalid?: (issues: FieldIssue[]) => void;
+}

package/dist/embed/engine.js

@@ -0,0 +1,17 @@
+/**
+ * `@texuli/blocks/embed/engine` — Svelte-free embed sandbox helpers and parsers.
+ */
+export { createSandboxedEmbedIframe, createSandboxedEmbedMount, EMBED_IFRAME_REFERRER_POLICY, EMBED_IFRAME_SANDBOX, EMBED_IFRAME_SANDBOX_POPUPS_ESCAPE, embedIframeSandbox, resolveEmbedFrameSrc, } from "./sandbox.js";
+export { checkEmbedBlock, EMBED_APP_MAX_BYTES, safeParseEmbedBlock } from "./schema.js";
+export const EMBED_BLOCK_TYPES = ['embed-app', 'link-preview'];
+export const DEFAULT_EMBED_BLOCK_LABELS = {
+    invalid: 'This embed block is not valid.',
+    start: 'Start the app',
+    starting: 'Starting…',
+    close: 'Close app',
+    unavailable: 'This host cannot start embedded apps.',
+    idle: 'Nothing loads until you start the app.',
+    startError: 'The embedded app could not be started.',
+    link: 'Open link',
+    newWindow: 'Opens in a new tab',
+};

package/dist/embed/family.d.ts

@@ -0,0 +1,7 @@
+import type { Component } from 'svelte';
+import type { EmbedBlockViewProps } from './engine.js';
+export { DEFAULT_EMBED_BLOCK_LABELS, EMBED_BLOCK_TYPES, type EmbedBlockLabels, type EmbedBlockViewProps, type EmbedFamilyBlock, type EmbedFamilyBlockType, type EmbedMountCleanup, type EmbedMountResult, } from './engine.js';
+/** Loads the embed family as a separate Svelte chunk. */
+export declare function loadEmbedFamily(): Promise<{
+    default: Component<EmbedBlockViewProps>;
+}>;

package/dist/embed/family.js

@@ -0,0 +1,5 @@
+export { DEFAULT_EMBED_BLOCK_LABELS, EMBED_BLOCK_TYPES, } from "./engine.js";
+/** Loads the embed family as a separate Svelte chunk. */
+export function loadEmbedFamily() {
+    return import('./EmbedBlockView.svelte');
+}

package/dist/embed/index.d.ts

@@ -0,0 +1,5 @@
+/// <reference path="../css-modules.d.ts" />
+export { DEFAULT_EMBED_BLOCK_LABELS, EMBED_BLOCK_TYPES, type EmbedBlockLabels, type EmbedBlockViewProps, type EmbedFamilyBlock, type EmbedFamilyBlockType, type EmbedMountCleanup, type EmbedMountResult, loadEmbedFamily, } from './family.js';
+export { type CreateSandboxedEmbedIframeOptions, createSandboxedEmbedIframe, createSandboxedEmbedMount, EMBED_IFRAME_REFERRER_POLICY, EMBED_IFRAME_SANDBOX, EMBED_IFRAME_SANDBOX_POPUPS_ESCAPE, embedIframeSandbox, type ResolveEmbedFrameSrcOptions, resolveEmbedFrameSrc, type SandboxedEmbedMountOptions, } from './sandbox.js';
+export type { EmbedAppBlock, EmbedBlock, EmbedBlockCheck, EmbedParseResult, LinkPreviewBlock, } from './schema.js';
+export { checkEmbedBlock, EMBED_APP_MAX_BYTES, safeParseEmbedBlock } from './schema.js';

package/dist/embed/index.js

@@ -0,0 +1,3 @@
+export { DEFAULT_EMBED_BLOCK_LABELS, EMBED_BLOCK_TYPES, loadEmbedFamily, } from "./family.js";
+export { createSandboxedEmbedIframe, createSandboxedEmbedMount, EMBED_IFRAME_REFERRER_POLICY, EMBED_IFRAME_SANDBOX, EMBED_IFRAME_SANDBOX_POPUPS_ESCAPE, embedIframeSandbox, resolveEmbedFrameSrc, } from "./sandbox.js";
+export { checkEmbedBlock, EMBED_APP_MAX_BYTES, safeParseEmbedBlock } from "./schema.js";

package/dist/embed/renderers.d.ts

@@ -0,0 +1,3 @@
+export { default as EmbedApp } from './EmbedApp.svelte';
+export { default as EmbedBlockView } from './EmbedBlockView.svelte';
+export { default as LinkPreview } from './LinkPreview.svelte';

package/dist/embed/renderers.js

@@ -0,0 +1,3 @@
+export { default as EmbedApp } from './EmbedApp.svelte';
+export { default as EmbedBlockView } from './EmbedBlockView.svelte';
+export { default as LinkPreview } from './LinkPreview.svelte';

package/dist/embed/sandbox.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Host helper for sandboxed embed iframes (F5 / SECURITY.md embed contract).
+ *
+ * Texuli never evaluates embed-app JSON. When a host needs a URL frame, this
+ * module builds an iframe that:
+ * - uses a sandbox **without** `allow-same-origin` (opaque origin)
+ * - sets `referrerpolicy="no-referrer"`
+ * - accepts only HTTPS `src` values whose origin is on an explicit allowlist
+ * - omits `allow-popups-to-escape-sandbox` by default (opt in only)
+ *
+ * The host must still set CSP `frame-src`, check `postMessage` origins, and
+ * must never widen the sandbox string returned here casually.
+ */
+/** Cleanup returned by a host mountEmbed implementation. */
+export type EmbedMountCleanup = () => void;
+export type EmbedMountResult = void | EmbedMountCleanup;
+/**
+ * Default sandbox tokens for embed iframes. Intentionally omits:
+ * - `allow-same-origin` (frame cannot read the parent document)
+ * - `allow-popups-to-escape-sandbox` (popups stay sandboxed unless opted in)
+ */
+export declare const EMBED_IFRAME_SANDBOX: "allow-scripts allow-forms allow-popups";
+/** Optional extra token when the host accepts unsandboxed popups from the frame. */
+export declare const EMBED_IFRAME_SANDBOX_POPUPS_ESCAPE: "allow-popups-to-escape-sandbox";
+/** Referrer policy applied to every sandboxed embed iframe. */
+export declare const EMBED_IFRAME_REFERRER_POLICY: "no-referrer";
+export type EmbedSandboxOptions = {
+    /**
+     * When true, appends `allow-popups-to-escape-sandbox` so a user-gesture popup
+     * from the frame runs with a full top-level origin (phishing risk). Default false.
+     */
+    allowPopupsToEscapeSandbox?: boolean;
+};
+/** Build the sandbox attribute value for an embed iframe. */
+export declare function embedIframeSandbox(options?: EmbedSandboxOptions): string;
+export type ResolveEmbedFrameSrcOptions = {
+    /** Exact HTTPS origins permitted as iframe `src` (e.g. `https://widgets.example.com`). */
+    allowedOrigins: readonly string[];
+};
+/**
+ * Validate an iframe `src` for an untrusted embed frame.
+ * Returns the cleaned URL or `undefined` when the value must not load.
+ */
+export declare function resolveEmbedFrameSrc(value: unknown, options: ResolveEmbedFrameSrcOptions): string | undefined;
+export type CreateSandboxedEmbedIframeOptions = {
+    /** Candidate frame URL (validated against `allowedOrigins`). */
+    src: unknown;
+    /** Exact HTTPS origins allowed for `src`. */
+    allowedOrigins: readonly string[];
+    /** Accessible name for the iframe. */
+    title?: string;
+    /**
+     * Opt-in: allow popups opened by the frame to escape the sandbox.
+     * Default false — popups stay constrained.
+     */
+    allowPopupsToEscapeSandbox?: boolean;
+};
+/**
+ * Build a sandboxed iframe element, or `null` when `src` is refused.
+ * Does not attach the element to the document.
+ */
+export declare function createSandboxedEmbedIframe(options: CreateSandboxedEmbedIframeOptions): HTMLIFrameElement | null;
+export type SandboxedEmbedMountOptions = {
+    /** Exact HTTPS origins allowed when `app.src` (or `resolveSrc`) yields a URL. */
+    allowedOrigins: readonly string[];
+    /**
+     * Optional map from validated embed-app JSON to a frame URL.
+     * Default reads `app.src` when it is a string.
+     */
+    resolveSrc?: (app: Record<string, unknown>) => unknown;
+    /** Iframe accessible name; defaults to `app.title` or "Embedded app". */
+    title?: string | ((app: Record<string, unknown>) => string);
+    /**
+     * Opt-in: allow popups from the frame to escape the sandbox.
+     * Default false.
+     */
+    allowPopupsToEscapeSandbox?: boolean;
+};
+/**
+ * Factory for a host `mountEmbed` that loads allowlisted HTTPS URLs in a
+ * sandboxed, no-referrer iframe. Returns a cleanup that removes the frame.
+ *
+ * If the resolved src is not allowlisted, the mount throws so EmbedApp shows
+ * the start-error label instead of painting an open frame.
+ */
+export declare function createSandboxedEmbedMount(options: SandboxedEmbedMountOptions): (target: HTMLElement, app: Record<string, unknown>) => EmbedMountResult;

package/dist/embed/sandbox.js

@@ -0,0 +1,114 @@
+/**
+ * Default sandbox tokens for embed iframes. Intentionally omits:
+ * - `allow-same-origin` (frame cannot read the parent document)
+ * - `allow-popups-to-escape-sandbox` (popups stay sandboxed unless opted in)
+ */
+export const EMBED_IFRAME_SANDBOX = 'allow-scripts allow-forms allow-popups';
+/** Optional extra token when the host accepts unsandboxed popups from the frame. */
+export const EMBED_IFRAME_SANDBOX_POPUPS_ESCAPE = 'allow-popups-to-escape-sandbox';
+/** Referrer policy applied to every sandboxed embed iframe. */
+export const EMBED_IFRAME_REFERRER_POLICY = 'no-referrer';
+/** Build the sandbox attribute value for an embed iframe. */
+export function embedIframeSandbox(options = {}) {
+    if (options.allowPopupsToEscapeSandbox === true) {
+        return `${EMBED_IFRAME_SANDBOX} ${EMBED_IFRAME_SANDBOX_POPUPS_ESCAPE}`;
+    }
+    return EMBED_IFRAME_SANDBOX;
+}
+function normalizeAllowedOrigins(origins) {
+    const out = new Set();
+    for (const entry of origins) {
+        if (typeof entry !== 'string' || entry.trim() === '')
+            continue;
+        try {
+            const url = new URL(entry.includes('://') ? entry : `https://${entry}`);
+            if (url.protocol !== 'https:')
+                continue;
+            if (url.username !== '' || url.password !== '')
+                continue;
+            out.add(url.origin);
+        }
+        catch {
+            // ignore malformed allowlist rows
+        }
+    }
+    return out;
+}
+/**
+ * Validate an iframe `src` for an untrusted embed frame.
+ * Returns the cleaned URL or `undefined` when the value must not load.
+ */
+export function resolveEmbedFrameSrc(value, options) {
+    if (typeof value !== 'string')
+        return undefined;
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: control chars are stripped on purpose
+    const cleaned = value.trim().replace(/[\u0000-\u001f\u007f]/g, '');
+    if (cleaned === '' || cleaned.startsWith('//') || cleaned.startsWith('\\'))
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(cleaned);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== 'https:')
+        return undefined;
+    if (parsed.username !== '' || parsed.password !== '')
+        return undefined;
+    if (!normalizeAllowedOrigins(options.allowedOrigins).has(parsed.origin))
+        return undefined;
+    return parsed.href;
+}
+/**
+ * Build a sandboxed iframe element, or `null` when `src` is refused.
+ * Does not attach the element to the document.
+ */
+export function createSandboxedEmbedIframe(options) {
+    const src = resolveEmbedFrameSrc(options.src, {
+        allowedOrigins: options.allowedOrigins,
+    });
+    if (!src)
+        return null;
+    const iframe = document.createElement('iframe');
+    iframe.setAttribute('sandbox', embedIframeSandbox({ allowPopupsToEscapeSandbox: options.allowPopupsToEscapeSandbox }));
+    iframe.setAttribute('referrerpolicy', EMBED_IFRAME_REFERRER_POLICY);
+    iframe.setAttribute('title', options.title?.trim() || 'Embedded app');
+    iframe.src = src;
+    return iframe;
+}
+/**
+ * Factory for a host `mountEmbed` that loads allowlisted HTTPS URLs in a
+ * sandboxed, no-referrer iframe. Returns a cleanup that removes the frame.
+ *
+ * If the resolved src is not allowlisted, the mount throws so EmbedApp shows
+ * the start-error label instead of painting an open frame.
+ */
+export function createSandboxedEmbedMount(options) {
+    const allowedOrigins = options.allowedOrigins;
+    return (target, app) => {
+        const rawSrc = options.resolveSrc?.(app) ??
+            (typeof app.src === 'string' ? app.src : typeof app.url === 'string' ? app.url : undefined);
+        const title = typeof options.title === 'function'
+            ? options.title(app)
+            : (options.title ??
+                (typeof app.title === 'string' ? app.title : undefined) ??
+                'Embedded app');
+        const iframe = createSandboxedEmbedIframe({
+            src: rawSrc,
+            allowedOrigins,
+            title,
+            allowPopupsToEscapeSandbox: options.allowPopupsToEscapeSandbox,
+        });
+        if (!iframe) {
+            throw new Error('Embed frame src is missing or not on the host allowlist.');
+        }
+        target.replaceChildren(iframe);
+        const cleanup = () => {
+            iframe.removeAttribute('src');
+            iframe.remove();
+            target.replaceChildren();
+        };
+        return cleanup;
+    };
+}

package/dist/embed/schema.d.ts

@@ -0,0 +1,30 @@
+import type { BlockBase, FieldIssue, ParseResult } from '../core/schema/primitives.js';
+export declare const EMBED_BLOCK_TYPES: readonly ["embed-app", "link-preview"];
+export declare const EMBED_APP_MAX_BYTES = 2400;
+export type EmbedAppBlock = BlockBase & {
+    type: 'embed-app';
+    title: string;
+    startLabel?: string;
+    height?: 'sm' | 'md' | 'lg';
+    app: Record<string, unknown>;
+};
+export type LinkPreviewBlock = BlockBase & {
+    type: 'link-preview';
+    href: string;
+    title: string;
+    description?: string;
+    site?: string;
+};
+export type EmbedBlock = EmbedAppBlock | LinkPreviewBlock;
+export type EmbedParseResult = ParseResult<EmbedBlock>;
+export type EmbedBlockCheck = {
+    ok: true;
+    block: EmbedBlock;
+} | {
+    ok: false;
+    issues: FieldIssue[];
+};
+/** Validate a link preview or app frame block before exposing it to a renderer. */
+export declare function safeParseEmbedBlock(value: unknown): EmbedParseResult;
+/** Renderer-facing validation result, with untrusted values kept inert on failure. */
+export declare function checkEmbedBlock(value: unknown): EmbedBlockCheck;