@ccheever/exact-renderer 0.1.0

package/src/svelte.ts

@@ -0,0 +1,349 @@
+/**
+ * Exact Svelte Adapter
+ *
+ * RFC 0043 routes Svelte through the DOM shim rather than a framework-native
+ * host config. Modern Svelte still expects browser globals during runtime
+ * startup, so this adapter installs a narrow compatibility layer that points
+ * Svelte's `document`/`window` access at an Exact DOM handle.
+ *
+ * Important tradeoff:
+ * - The DOM shim itself is multi-root safe.
+ * - The Svelte runtime snapshots global DOM constructors on first client init.
+ * - To keep the adapter correct without forking Svelte internals, we allow one
+ *   mounted Svelte root at a time. Additional roots can exist sequentially, but
+ *   not concurrently.
+ *
+ * That is sufficient for the first-party Frameworks Lab and the common
+ * "single app root" Exact usage pattern, while keeping the adapter code small
+ * and understandable.
+ */
+
+import type { Component, ComponentType } from 'svelte';
+import {
+  flushSync,
+  mount as mountSvelteComponent,
+  settled,
+  tick,
+  unmount as unmountSvelteComponent,
+} from 'svelte';
+
+import { _clearHandlers } from './host-ops.js';
+import {
+  ExactComment,
+  ExactDocument,
+  ExactDocumentFragment,
+  ExactElement,
+  ExactNodeBase,
+  ExactRootBodyElement,
+  ExactText,
+  ExactWindow,
+  createExactDOM,
+  type ExactDOMHandle,
+} from './dom-shim.js';
+
+type SvelteComponentLike<Props extends Record<string, any>, Exports extends Record<string, any>> =
+  | ComponentType<any>
+  | Component<Props, Exports, any>;
+
+interface ExactSvelteRootState {
+  readonly rootId: number;
+  dom: ExactDOMHandle;
+  instance: Record<string, any> | null;
+  claimed: boolean;
+}
+
+export interface ExactSvelteMountOptions<Props extends Record<string, any> = Record<string, any>> {
+  readonly rootId?: number;
+  readonly target?: ExactRootBodyElement | ExactElement | ExactDocument | ExactDocumentFragment;
+  readonly anchor?: ExactNodeBase | null;
+  readonly props?: Props;
+  readonly events?: Record<string, (event: unknown) => unknown>;
+  readonly context?: Map<any, any>;
+  readonly intro?: boolean;
+  readonly transformError?: (error: unknown) => unknown | Promise<unknown>;
+}
+
+export interface ExactSvelteRoot {
+  readonly rootId: number;
+  render<Props extends Record<string, any>, Exports extends Record<string, any>>(
+    component: SvelteComponentLike<Props, Exports>,
+    options?: Omit<ExactSvelteMountOptions<Props>, 'rootId'>,
+  ): Exports;
+  unmount(): Promise<void>;
+  destroy(): Promise<void>;
+}
+
+const rootStates = new Map<number, ExactSvelteRootState>();
+
+let activeMountedRootId: number | null = null;
+let compatGlobalsInstalled = false;
+
+const hostDocument =
+  typeof globalThis.document === 'object' && globalThis.document !== null
+    ? globalThis.document
+    : undefined;
+const hostWindow =
+  typeof globalThis.window === 'object' && globalThis.window !== null
+    ? globalThis.window
+    : undefined;
+const hostNavigator =
+  typeof globalThis.navigator === 'object' && globalThis.navigator !== null
+    ? globalThis.navigator
+    : undefined;
+
+function getRootState(rootId: number): ExactSvelteRootState {
+  let state = rootStates.get(rootId);
+  if (!state) {
+    state = {
+      rootId,
+      dom: createExactDOM({ rootId }),
+      instance: null,
+      claimed: false,
+    };
+    rootStates.set(rootId, state);
+  }
+  return state;
+}
+
+function getActiveMountedState(): ExactSvelteRootState | null {
+  if (activeMountedRootId === null) {
+    return null;
+  }
+  return rootStates.get(activeMountedRootId) ?? null;
+}
+
+function resolveCurrentDocument(): ExactDocument | Document {
+  const active = getActiveMountedState();
+  if (active) {
+    return active.dom.document;
+  }
+  if (hostDocument) {
+    return hostDocument;
+  }
+  throw new Error('[ExactSvelte] No active Exact DOM document is available.');
+}
+
+function resolveCurrentWindow(): ExactWindow | Window {
+  const active = getActiveMountedState();
+  if (active) {
+    return active.dom.window;
+  }
+  if (hostWindow) {
+    return hostWindow;
+  }
+  throw new Error('[ExactSvelte] No active Exact DOM window is available.');
+}
+
+const documentProxy = new Proxy({} as ExactDocument, {
+  get(_target, prop) {
+    const document = resolveCurrentDocument() as unknown as Record<PropertyKey, unknown>;
+    const value = document[prop];
+    return typeof value === 'function' ? value.bind(document) : value;
+  },
+  set(_target, prop, value) {
+    (resolveCurrentDocument() as unknown as Record<PropertyKey, unknown>)[prop] = value;
+    return true;
+  },
+  has(_target, prop) {
+    return prop in (resolveCurrentDocument() as unknown as Record<PropertyKey, unknown>);
+  },
+});
+
+const windowProxy = new Proxy({} as ExactWindow, {
+  get(_target, prop) {
+    const window = resolveCurrentWindow() as unknown as Record<PropertyKey, unknown>;
+    const value = window[prop];
+    return typeof value === 'function' ? value.bind(window) : value;
+  },
+  set(_target, prop, value) {
+    (resolveCurrentWindow() as unknown as Record<PropertyKey, unknown>)[prop] = value;
+    return true;
+  },
+  has(_target, prop) {
+    return prop in (resolveCurrentWindow() as unknown as Record<PropertyKey, unknown>);
+  },
+});
+
+function defineCompatGlobal(name: string, value: unknown): void {
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis, name);
+  if (descriptor?.configurable === false) {
+    return;
+  }
+
+  Object.defineProperty(globalThis, name, {
+    value,
+    writable: true,
+    configurable: true,
+  });
+}
+
+function ensureCompatGlobals(): void {
+  if (compatGlobalsInstalled) {
+    return;
+  }
+
+  // The adapter is meant for Exact's non-browser runtime. Overwriting a live
+  // browser DOM would make the host page incoherent, so fail loudly there.
+  if (hostDocument && hostDocument !== (documentProxy as unknown as Document)) {
+    throw new Error(
+      '[ExactSvelte] The Exact Svelte adapter cannot replace an existing browser DOM. Use it from the Exact runtime, not inside a live web page.',
+    );
+  }
+
+  defineCompatGlobal('window', windowProxy);
+  defineCompatGlobal('document', documentProxy);
+  defineCompatGlobal('navigator', hostNavigator ?? { userAgent: 'ExactSvelte/1.0' });
+
+  // Svelte snapshots these constructor prototypes during client runtime init.
+  // They only need to describe the shim node surface, not a full browser DOM.
+  defineCompatGlobal('Node', ExactNodeBase);
+  defineCompatGlobal('Element', ExactElement);
+  defineCompatGlobal('Text', ExactText);
+  defineCompatGlobal('Comment', ExactComment);
+  defineCompatGlobal('Document', ExactDocument);
+  defineCompatGlobal('DocumentFragment', ExactDocumentFragment);
+  defineCompatGlobal('ShadowRoot', ExactDocumentFragment);
+  defineCompatGlobal('HTMLMediaElement', class HTMLMediaElementStub {});
+
+  compatGlobalsInstalled = true;
+}
+
+function activateMountedRoot(state: ExactSvelteRootState): void {
+  const active = getActiveMountedState();
+  if (active && active.rootId !== state.rootId && active.instance !== null) {
+    throw new Error(
+      '[ExactSvelte] Only one mounted Svelte root is supported at a time because the Svelte client runtime captures global DOM state during initialization.',
+    );
+  }
+
+  activeMountedRootId = state.rootId;
+}
+
+async function destroyRootState(state: ExactSvelteRootState): Promise<void> {
+  if (state.instance) {
+    await unmountMountedRoot(state);
+  }
+
+  state.dom.destroy();
+  rootStates.delete(state.rootId);
+
+  if (activeMountedRootId === state.rootId) {
+    activeMountedRootId = null;
+  }
+}
+
+async function unmountMountedRoot(state: ExactSvelteRootState): Promise<void> {
+  if (!state.instance) {
+    return;
+  }
+
+  activateMountedRoot(state);
+
+  // `unmount()` returns a promise, but without outros the DOM removal happens
+  // synchronously. `flushSync()` keeps the Svelte runtime and the DOM shim in a
+  // deterministic state before we continue.
+  const unmountPromise = unmountSvelteComponent(state.instance);
+  flushSync();
+  await unmountPromise;
+  state.instance = null;
+
+  if (activeMountedRootId === state.rootId) {
+    activeMountedRootId = null;
+  }
+}
+
+function mountIntoRoot<Props extends Record<string, any>, Exports extends Record<string, any>>(
+  state: ExactSvelteRootState,
+  component: SvelteComponentLike<Props, Exports>,
+  options: Omit<ExactSvelteMountOptions<Props>, 'rootId'> = {},
+): Exports {
+  ensureCompatGlobals();
+  activateMountedRoot(state);
+
+  if (state.instance) {
+    // Rendering over an existing tree mirrors the React/Solid/Vue adapter
+    // ergonomics. We remove the previous component first and reuse the Exact
+    // root surface underneath it.
+    void unmountSvelteComponent(state.instance);
+    state.instance = null;
+  }
+
+  const instance = mountSvelteComponent(component as any, {
+    target: (options.target ?? state.dom.document.body) as any,
+    anchor: (options.anchor ?? undefined) as any,
+    props: options.props,
+    events: options.events,
+    context: options.context,
+    intro: options.intro,
+    transformError: options.transformError,
+  } as any);
+
+  state.instance = instance as Record<string, any>;
+  flushSync();
+
+  return instance as Exports;
+}
+
+export function mount<Props extends Record<string, any>, Exports extends Record<string, any>>(
+  component: SvelteComponentLike<Props, Exports>,
+  options: ExactSvelteMountOptions<Props> = {},
+): Exports {
+  const state = getRootState(options.rootId ?? 0);
+  return mountIntoRoot(state, component, options);
+}
+
+export function render<Props extends Record<string, any>, Exports extends Record<string, any>>(
+  component: SvelteComponentLike<Props, Exports>,
+  options: Omit<ExactSvelteMountOptions<Props>, 'rootId'> = {},
+): () => Promise<void> {
+  const state = getRootState(0);
+  mountIntoRoot(state, component, options);
+  return () => unmountMountedRoot(state);
+}
+
+export async function unmount(): Promise<void> {
+  const state = rootStates.get(0);
+  if (!state) {
+    return;
+  }
+  await unmountMountedRoot(state);
+}
+
+export function createExactRoot(rootId: number): ExactSvelteRoot {
+  if (rootId === 0) {
+    throw new Error('createExactRoot: rootId must be > 0. Use render() for the default root.');
+  }
+
+  const state = getRootState(rootId);
+  if (state.claimed) {
+    throw new Error(`createExactRoot: rootId ${rootId} is already in use.`);
+  }
+  state.claimed = true;
+
+  return {
+    rootId,
+    render(component, options) {
+      return mountIntoRoot(state, component, options);
+    },
+    async unmount() {
+      await unmountMountedRoot(state);
+    },
+    async destroy() {
+      state.claimed = false;
+      await destroyRootState(state);
+    },
+  };
+}
+
+export const createSvelteRoot = createExactRoot;
+
+export async function reset(): Promise<void> {
+  for (const state of [...rootStates.values()]) {
+    await destroyRootState(state);
+  }
+  _clearHandlers();
+}
+
+// Re-export the small subset of the Svelte runtime that Exact app code commonly
+// wants from the adapter entrypoint during demos and tests.
+export { flushSync, settled, tick };

package/src/svg-source.ts

@@ -0,0 +1,222 @@
+import { isAssetRef } from '@exact/core/assets-fonts-state';
+
+import type { ImageCandidate, ImageSource, SvgSource } from './types.js';
+
+export interface ResolvedSvgRequest {
+  readonly headers?: Record<string, string>;
+  readonly markup?: string;
+  readonly uri?: string;
+}
+
+export function isInlineSvgSource(source: SvgSource | undefined): boolean {
+  return typeof source === 'string' &&
+    (source.trimStart().startsWith('<') || source.trimStart().startsWith('<?xml'));
+}
+
+export function resolveSvgSourceForDOM(source: SvgSource | undefined): string | undefined {
+  if (source == null) {
+    return undefined;
+  }
+
+  if (typeof source === 'string' && source.length > 0) {
+    return source;
+  }
+
+  if (isAssetRef(source)) {
+    return source.url;
+  }
+
+  if (typeof source === 'object' && source !== null && typeof source.uri === 'string' && source.uri.length > 0) {
+    return source.uri;
+  }
+
+  return undefined;
+}
+
+/**
+ * Resolve an SVG source to a string the native image pipeline can load.
+ *
+ * Native renderers (the AppKit/UIKit presenters' `applyNativeImage`) load a
+ * glyph from a named asset, a file/remote URL, or a `data:` URI — they cannot
+ * consume a raw inline `<svg>` markup string the way the DOM mirror can (which
+ * parses the markup into a live `<svg>` host). Inline markup is therefore
+ * wrapped as a percent-encoded `data:image/svg+xml` URI: `encodeURIComponent`
+ * (not base64) keeps the transform dependency-free on Hermes and the payload
+ * inspectable. URL / asset / already-`data:` sources pass through unchanged so
+ * `NSImage`/`UIImage` can fetch them directly.
+ */
+export function resolveSvgSourceForNative(source: SvgSource | undefined): string | undefined {
+  const resolved = resolveSvgSourceForDOM(source);
+  if (resolved == null || resolved.length === 0) {
+    return undefined;
+  }
+
+  if (isInlineSvgSource(resolved)) {
+    return `data:image/svg+xml,${encodeURIComponent(resolved)}`;
+  }
+
+  return resolved;
+}
+
+export function resolveSvgSourceForFetch(source: SvgSource | undefined): ResolvedSvgRequest | undefined {
+  if (source == null) {
+    return undefined;
+  }
+
+  if (typeof source === 'string' && isInlineSvgSource(source)) {
+    return { markup: source };
+  }
+
+  if (typeof source === 'string') {
+    const decodedMarkup = decodeSvgDataUrl(source);
+    if (decodedMarkup !== undefined) {
+      return { markup: decodedMarkup };
+    }
+    return source !== '' ? { uri: source } : undefined;
+  }
+
+  if (isAssetRef(source)) {
+    return { uri: source.url };
+  }
+
+  if (typeof source === 'object' && source !== null && typeof source.uri === 'string' && source.uri.length > 0) {
+    const decodedMarkup = decodeSvgDataUrl(source.uri);
+    if (decodedMarkup !== undefined) {
+      return { markup: decodedMarkup };
+    }
+    return { uri: source.uri, headers: source.headers };
+  }
+
+  return undefined;
+}
+
+export function coerceImageSourceToSvgSource(source: ImageSource | undefined): SvgSource | undefined {
+  if (source == null || typeof source === 'number') {
+    return undefined;
+  }
+
+  if (typeof source === 'string') {
+    return isInlineSvgSource(source) || isSvgLikeUri(source) ? source : undefined;
+  }
+
+  if (isAssetRef(source)) {
+    return isSvgLikeUri(source.url) ? source : undefined;
+  }
+
+  if (isImageCandidateArraySource(source)) {
+    const candidate = source.find((entry) => isSvgImageCandidate(entry));
+    if (!candidate) {
+      return undefined;
+    }
+    return {
+      uri: candidate.uri,
+      headers: candidate.headers,
+      cacheKey: candidate.cacheKey,
+    };
+  }
+
+  if (typeof source === 'object' && source !== null && 'thumbhash' in source) {
+    return undefined;
+  }
+
+  if (isSvgUriSourceLike(source)) {
+    return isSvgLikeUri(source.uri) ? source : undefined;
+  }
+
+  return undefined;
+}
+
+export function filterSvgColors(
+  colors: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (colors == null) {
+    return undefined;
+  }
+
+  const filtered = Object.fromEntries(
+    Object.entries(colors).filter(([key, value]) => key.startsWith('--') && value.length > 0),
+  );
+
+  return Object.keys(filtered).length > 0 ? filtered : undefined;
+}
+
+export function getDefaultSvgPixelDensity(): number {
+  const devicePixelRatio = (
+    globalThis as typeof globalThis & { devicePixelRatio?: unknown }
+  ).devicePixelRatio;
+  if (typeof devicePixelRatio === 'number' && isFinite(devicePixelRatio) && devicePixelRatio > 0) {
+    return devicePixelRatio;
+  }
+
+  const exact = (globalThis as { exact?: { screenScale?: unknown } }).exact;
+  if (typeof exact?.screenScale === 'number' && isFinite(exact.screenScale) && exact.screenScale > 0) {
+    return exact.screenScale;
+  }
+
+  return 1;
+}
+
+function decodeSvgDataUrl(input: string): string | undefined {
+  if (!input.startsWith('data:image/svg+xml')) {
+    return undefined;
+  }
+
+  const commaIndex = input.indexOf(',');
+  if (commaIndex === -1) {
+    return undefined;
+  }
+
+  const metadata = input.slice(0, commaIndex).toLowerCase();
+  const payload = input.slice(commaIndex + 1);
+
+  try {
+    if (metadata.includes(';base64')) {
+      if (typeof Buffer !== 'undefined') {
+        return Buffer.from(payload, 'base64').toString('utf8');
+      }
+      if (typeof Uint8Array !== 'undefined' && typeof TextDecoder !== 'undefined') {
+        const binary = atob(payload);
+        const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+        return new TextDecoder().decode(bytes);
+      }
+      return atob(payload);
+    }
+
+    return decodeURIComponent(payload);
+  } catch {
+    return undefined;
+  }
+}
+
+function isSvgLikeUri(uri: string): boolean {
+  const normalized = uri.trim();
+  if (normalized.length === 0) {
+    return false;
+  }
+
+  if (normalized.startsWith('data:image/svg+xml')) {
+    return true;
+  }
+
+  const withoutHash = normalized.split('#', 1)[0] ?? normalized;
+  const withoutQuery = withoutHash.split('?', 1)[0] ?? withoutHash;
+  return /\.svgz?$/i.test(withoutQuery);
+}
+
+function isSvgImageCandidate(candidate: ImageCandidate): boolean {
+  return isSvgLikeUri(candidate.uri) || normalizeMimeType(candidate.type) === 'image/svg+xml';
+}
+
+function isImageCandidateArraySource(source: ImageSource): source is readonly ImageCandidate[] {
+  return Array.isArray(source);
+}
+
+function isSvgUriSourceLike(
+  source: Exclude<ImageSource, string | number | readonly ImageCandidate[]>,
+): source is { uri: string; headers?: Record<string, string>; cacheKey?: string } {
+  return typeof source === 'object' && source !== null && 'uri' in source && typeof source.uri === 'string';
+}
+
+function normalizeMimeType(type: string | undefined): string {
+  return type?.split(';', 1)[0]?.trim().toLowerCase() ?? '';
+}

package/src/tags/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Tag Mapping - Public Exports
+ *
+ * This module re-exports the tag mapping types and functions.
+ */
+
+export {
+  type NativeViewTagMetadata,
+  type NativeViewTagSelection,
+  type TagConfig,
+  getTagConfig,
+  isValidTag,
+  isWebTag,
+  isRNTag,
+  getWebTags,
+  getRNTags,
+  getAllTags,
+  registerNativeViewTag,
+  defaultTagConfig,
+  _clearNativeViewTagsForTesting,
+} from './tag-map.js';