@typecaast/react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,138 @@
+import { CSSProperties, ReactNode } from 'react';
+import { Config, ThemeMode, FitMode, Participant, Size } from '@typecaast/schema';
+import { Skin } from '@typecaast/skin-kit';
+import { SimState, Player, Capabilities, ResolvedTheme } from '@typecaast/core';
+
+interface TypecaastProps {
+    config: Config;
+    skin: Skin;
+    /** Force a theme; otherwise resolved from `config.meta.theme`. */
+    theme?: ThemeMode;
+    autoplay?: boolean;
+    loop?: boolean;
+    rate?: number;
+    /** Container fit mode; defaults to `config.meta.fit`. */
+    fit?: FitMode;
+    /** Accessible label for the simulation. */
+    label?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Mounts the real-time player and renders the resolved skin from live state.
+ * The animated visuals are `aria-hidden`; an accessible transcript carries the
+ * conversation for screen readers, and `prefers-reduced-motion` snaps to the
+ * final state instead of animating (PLAN §20).
+ */
+declare function Typecaast({ config, skin, theme, autoplay, loop, rate, fit, label, className, style, }: TypecaastProps): ReactNode;
+
+interface UseTypecaastOptions {
+    /** Force a theme; otherwise resolved from `config.meta.theme`. */
+    theme?: ThemeMode;
+    autoplay?: boolean;
+    loop?: boolean;
+    rate?: number;
+    /** The active skin's capabilities, to drop what it can't render. */
+    capabilities?: Capabilities;
+}
+/** Imperative controls + live state returned by {@link useTypecaast}. */
+interface TypecaastControls {
+    state: SimState;
+    /** Current playback time in ms (reactive). */
+    currentMs: number;
+    play(): void;
+    pause(): void;
+    seek(timeMs: number): void;
+    scrubTo(timeMs: number): void;
+    setRate(rate: number): void;
+    stepNext(): void;
+    stepPrev(): void;
+    duration: number;
+    rate: number;
+    playing: boolean;
+    /** Escape hatch to the underlying player. */
+    player: Player;
+}
+/**
+ * Mount a player for a config and expose live state + controls. The player
+ * owns the clock (rAF in the browser); this hook bridges its ticks into React
+ * state. The builder uses these controls for preview-as-you-go editing.
+ *
+ * In M1-UI the player runs over the mocked engine (see engine-adapter); the
+ * hook's surface is the final one and does not change when the real engine
+ * lands.
+ */
+declare function useTypecaast(config: Config, options?: UseTypecaastOptions): TypecaastControls;
+
+interface TypecaastStageProps {
+    state: SimState;
+    skin: Skin;
+    participants: Participant[];
+    /** Skin-specific options from `meta.skin.options`. */
+    options?: Record<string, unknown>;
+}
+/**
+ * Maps a `SimState` onto a skin's components: a `Frame` wrapping the thread
+ * items (Message / SystemMessage), the typing indicators, and the composer.
+ * Reactions render inside the skin's `Message` (it reads `message.reactions`).
+ */
+declare function TypecaastStage({ state, skin, participants, options, }: TypecaastStageProps): ReactNode;
+
+/**
+ * Resolve a theme mode to a concrete theme. `auto` falls back to `light`
+ * here; M1U.4 makes `auto` reactive against the host `prefers-color-scheme`
+ * via a hook layered on top of this.
+ */
+declare function resolveTheme(mode: ThemeMode): ResolvedTheme;
+
+/** Reactively tracks the host's `prefers-color-scheme: dark`. */
+declare function usePrefersDark(): boolean;
+/**
+ * Resolve a theme mode to a concrete theme. `light`/`dark` are forced; `auto`
+ * tracks the host `prefers-color-scheme` reactively and falls back to `light`
+ * when no preference signal is available.
+ */
+declare function useResolvedTheme(mode: ThemeMode): ResolvedTheme;
+
+/**
+ * Tracks `prefers-reduced-motion: reduce`. When true, the player snaps to the
+ * final state instead of animating (PLAN §20).
+ */
+declare function useReducedMotion(): boolean;
+
+type FontLoadState = "loading" | "loaded";
+/**
+ * Load a skin's declared web fonts on mount so the live preview renders in the
+ * correct typeface (PLAN §19) — never relying on a host OS font. SSR-safe and
+ * a no-op off the DOM (resolves "loaded"). Re-runs if the skin's fonts change.
+ */
+declare function useSkinFonts(skin: Skin): FontLoadState;
+
+interface FitBoxProps {
+    fit: FitMode;
+    canvas: Size;
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Applies the `fit` strategy between the authoring canvas and the host
+ * container (PLAN §7):
+ * - `reflow`: fills width; content re-wraps (container query / ResizeObserver).
+ * - `scale`: renders at exact canvas size, CSS-scaled to fit (layout preserved).
+ * - `fixed`: exact canvas size, clipped.
+ */
+declare function FitBox({ fit, canvas, children, className, style, }: FitBoxProps): ReactNode;
+
+interface TranscriptLine {
+    name: string;
+    text: string;
+}
+/**
+ * Build a plain-text transcript from the authored config — the accessible
+ * representation of the conversation for screen readers (PLAN §20). The config
+ * is already structured text, so this is a faithful, non-animated version.
+ */
+declare function buildTranscript(config: Config): TranscriptLine[];
+
+export { FitBox, type FitBoxProps, type FontLoadState, type TranscriptLine, Typecaast, type TypecaastControls, type TypecaastProps, TypecaastStage, type TypecaastStageProps, type UseTypecaastOptions, buildTranscript, resolveTheme, usePrefersDark, useReducedMotion, useResolvedTheme, useSkinFonts, useTypecaast };

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+import { CSSProperties, ReactNode } from 'react';
+import { Config, ThemeMode, FitMode, Participant, Size } from '@typecaast/schema';
+import { Skin } from '@typecaast/skin-kit';
+import { SimState, Player, Capabilities, ResolvedTheme } from '@typecaast/core';
+
+interface TypecaastProps {
+    config: Config;
+    skin: Skin;
+    /** Force a theme; otherwise resolved from `config.meta.theme`. */
+    theme?: ThemeMode;
+    autoplay?: boolean;
+    loop?: boolean;
+    rate?: number;
+    /** Container fit mode; defaults to `config.meta.fit`. */
+    fit?: FitMode;
+    /** Accessible label for the simulation. */
+    label?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Mounts the real-time player and renders the resolved skin from live state.
+ * The animated visuals are `aria-hidden`; an accessible transcript carries the
+ * conversation for screen readers, and `prefers-reduced-motion` snaps to the
+ * final state instead of animating (PLAN §20).
+ */
+declare function Typecaast({ config, skin, theme, autoplay, loop, rate, fit, label, className, style, }: TypecaastProps): ReactNode;
+
+interface UseTypecaastOptions {
+    /** Force a theme; otherwise resolved from `config.meta.theme`. */
+    theme?: ThemeMode;
+    autoplay?: boolean;
+    loop?: boolean;
+    rate?: number;
+    /** The active skin's capabilities, to drop what it can't render. */
+    capabilities?: Capabilities;
+}
+/** Imperative controls + live state returned by {@link useTypecaast}. */
+interface TypecaastControls {
+    state: SimState;
+    /** Current playback time in ms (reactive). */
+    currentMs: number;
+    play(): void;
+    pause(): void;
+    seek(timeMs: number): void;
+    scrubTo(timeMs: number): void;
+    setRate(rate: number): void;
+    stepNext(): void;
+    stepPrev(): void;
+    duration: number;
+    rate: number;
+    playing: boolean;
+    /** Escape hatch to the underlying player. */
+    player: Player;
+}
+/**
+ * Mount a player for a config and expose live state + controls. The player
+ * owns the clock (rAF in the browser); this hook bridges its ticks into React
+ * state. The builder uses these controls for preview-as-you-go editing.
+ *
+ * In M1-UI the player runs over the mocked engine (see engine-adapter); the
+ * hook's surface is the final one and does not change when the real engine
+ * lands.
+ */
+declare function useTypecaast(config: Config, options?: UseTypecaastOptions): TypecaastControls;
+
+interface TypecaastStageProps {
+    state: SimState;
+    skin: Skin;
+    participants: Participant[];
+    /** Skin-specific options from `meta.skin.options`. */
+    options?: Record<string, unknown>;
+}
+/**
+ * Maps a `SimState` onto a skin's components: a `Frame` wrapping the thread
+ * items (Message / SystemMessage), the typing indicators, and the composer.
+ * Reactions render inside the skin's `Message` (it reads `message.reactions`).
+ */
+declare function TypecaastStage({ state, skin, participants, options, }: TypecaastStageProps): ReactNode;
+
+/**
+ * Resolve a theme mode to a concrete theme. `auto` falls back to `light`
+ * here; M1U.4 makes `auto` reactive against the host `prefers-color-scheme`
+ * via a hook layered on top of this.
+ */
+declare function resolveTheme(mode: ThemeMode): ResolvedTheme;
+
+/** Reactively tracks the host's `prefers-color-scheme: dark`. */
+declare function usePrefersDark(): boolean;
+/**
+ * Resolve a theme mode to a concrete theme. `light`/`dark` are forced; `auto`
+ * tracks the host `prefers-color-scheme` reactively and falls back to `light`
+ * when no preference signal is available.
+ */
+declare function useResolvedTheme(mode: ThemeMode): ResolvedTheme;
+
+/**
+ * Tracks `prefers-reduced-motion: reduce`. When true, the player snaps to the
+ * final state instead of animating (PLAN §20).
+ */
+declare function useReducedMotion(): boolean;
+
+type FontLoadState = "loading" | "loaded";
+/**
+ * Load a skin's declared web fonts on mount so the live preview renders in the
+ * correct typeface (PLAN §19) — never relying on a host OS font. SSR-safe and
+ * a no-op off the DOM (resolves "loaded"). Re-runs if the skin's fonts change.
+ */
+declare function useSkinFonts(skin: Skin): FontLoadState;
+
+interface FitBoxProps {
+    fit: FitMode;
+    canvas: Size;
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Applies the `fit` strategy between the authoring canvas and the host
+ * container (PLAN §7):
+ * - `reflow`: fills width; content re-wraps (container query / ResizeObserver).
+ * - `scale`: renders at exact canvas size, CSS-scaled to fit (layout preserved).
+ * - `fixed`: exact canvas size, clipped.
+ */
+declare function FitBox({ fit, canvas, children, className, style, }: FitBoxProps): ReactNode;
+
+interface TranscriptLine {
+    name: string;
+    text: string;
+}
+/**
+ * Build a plain-text transcript from the authored config — the accessible
+ * representation of the conversation for screen readers (PLAN §20). The config
+ * is already structured text, so this is a faithful, non-animated version.
+ */
+declare function buildTranscript(config: Config): TranscriptLine[];
+
+export { FitBox, type FitBoxProps, type FontLoadState, type TranscriptLine, Typecaast, type TypecaastControls, type TypecaastProps, TypecaastStage, type TypecaastStageProps, type UseTypecaastOptions, buildTranscript, resolveTheme, usePrefersDark, useReducedMotion, useResolvedTheme, useSkinFonts, useTypecaast };

package/dist/index.js

@@ -0,0 +1,386 @@
+import { useSyncExternalStore, useMemo, useState, useEffect, useRef, useLayoutEffect } from 'react';
+import { createPlayer, createEngine } from '@typecaast/core';
+import { loadSkinFonts, ThemeProvider } from '@typecaast/skin-kit';
+import { jsx, jsxs } from 'react/jsx-runtime';
+
+// src/typecaast.tsx
+function configToEngine(config, theme, capabilities) {
+  return createEngine(config, theme, capabilities);
+}
+var QUERY = "(prefers-color-scheme: dark)";
+function getMql() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return null;
+  }
+  return window.matchMedia(QUERY);
+}
+function subscribe(onChange) {
+  const mql = getMql();
+  if (!mql) return () => {
+  };
+  mql.addEventListener("change", onChange);
+  return () => mql.removeEventListener("change", onChange);
+}
+function getSnapshot() {
+  return getMql()?.matches ?? false;
+}
+function getServerSnapshot() {
+  return false;
+}
+function usePrefersDark() {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+function useResolvedTheme(mode) {
+  const prefersDark = usePrefersDark();
+  if (mode === "light") return "light";
+  if (mode === "dark") return "dark";
+  return prefersDark ? "dark" : "light";
+}
+
+// src/use-typecaast.ts
+function useTypecaast(config, options = {}) {
+  const {
+    theme,
+    autoplay = false,
+    loop = false,
+    rate = 1,
+    capabilities
+  } = options;
+  const resolved = useResolvedTheme(theme ?? config.meta.theme);
+  const player = useMemo(() => {
+    const engine = configToEngine(config, resolved, capabilities);
+    return createPlayer(engine.getStateAt, {
+      durationMs: engine.durationMs,
+      steps: engine.steps,
+      loop,
+      rate
+    });
+  }, [config, resolved, capabilities, loop, rate]);
+  const [state, setState] = useState(() => player.state);
+  const [currentMs, setCurrentMs] = useState(() => player.currentMs);
+  const [playing, setPlaying] = useState(() => player.playing);
+  useEffect(() => {
+    const sync = () => {
+      setState(player.state);
+      setCurrentMs(player.currentMs);
+    };
+    sync();
+    setPlaying(player.playing);
+    const offs = [
+      player.on("tick", sync),
+      player.on("seek", sync),
+      player.on("play", () => setPlaying(true)),
+      player.on("pause", () => setPlaying(false))
+    ];
+    if (autoplay) player.play();
+    return () => {
+      offs.forEach((off) => off());
+      player.destroy();
+    };
+  }, [player, autoplay]);
+  return {
+    state,
+    currentMs,
+    play: () => player.play(),
+    pause: () => player.pause(),
+    seek: (t) => player.seek(t),
+    scrubTo: (t) => player.scrubTo(t),
+    setRate: (r) => player.setRate(r),
+    stepNext: () => player.stepNext(),
+    stepPrev: () => player.stepPrev(),
+    duration: player.durationMs,
+    rate: player.rate,
+    playing,
+    player
+  };
+}
+function useSkinFonts(skin) {
+  const fonts = skin.meta.fonts;
+  const [state, setState] = useState(
+    () => fonts && fonts.length > 0 ? "loading" : "loaded"
+  );
+  useEffect(() => {
+    if (!fonts || fonts.length === 0) {
+      setState("loaded");
+      return;
+    }
+    let cancelled = false;
+    setState("loading");
+    loadSkinFonts(fonts).finally(() => {
+      if (!cancelled) setState("loaded");
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [fonts]);
+  return state;
+}
+var QUERY2 = "(prefers-reduced-motion: reduce)";
+function getMql2() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return null;
+  }
+  return window.matchMedia(QUERY2);
+}
+function subscribe2(onChange) {
+  const mql = getMql2();
+  if (!mql) return () => {
+  };
+  mql.addEventListener("change", onChange);
+  return () => mql.removeEventListener("change", onChange);
+}
+var getSnapshot2 = () => getMql2()?.matches ?? false;
+var getServerSnapshot2 = () => false;
+function useReducedMotion() {
+  return useSyncExternalStore(subscribe2, getSnapshot2, getServerSnapshot2);
+}
+
+// src/transcript.ts
+function buildTranscript(config) {
+  const name = new Map(config.participants.map((p) => [p.id, p.name]));
+  const lines = [];
+  for (const step of config.timeline) {
+    let from;
+    let text;
+    if (step.type === "message" || step.type === "system") {
+      from = step.from;
+      text = step.text;
+    } else if (step.type === "composerType") {
+      from = step.from;
+      text = step.text;
+    }
+    if (text) {
+      lines.push({ name: from ? name.get(from) ?? from : "System", text });
+    }
+  }
+  return lines;
+}
+function TypecaastStage({
+  state,
+  skin,
+  participants,
+  options
+}) {
+  const theme = state.theme;
+  const byId = useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const p of participants) map.set(p.id, p);
+    return map;
+  }, [participants]);
+  const { Frame, Message, SystemMessage, TypingIndicator, Composer } = skin.components;
+  const tokens = skin.tokens?.[theme];
+  const composerAuthor = state.composer.from ? byId.get(state.composer.from) : void 0;
+  return /* @__PURE__ */ jsx(ThemeProvider, { theme, tokens, children: /* @__PURE__ */ jsxs(Frame, { theme, options, children: [
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        "data-typecaast-thread": "",
+        style: {
+          display: "flex",
+          flexDirection: "column",
+          justifyContent: "flex-end",
+          flex: "1 1 auto",
+          minHeight: 0,
+          overflow: "hidden"
+        },
+        children: [
+          state.messages.map((message, i) => {
+            const author = byId.get(message.from);
+            if (!author) return null;
+            if (message.variant === "system") {
+              return /* @__PURE__ */ jsx(
+                SystemMessage,
+                {
+                  theme,
+                  message,
+                  author
+                },
+                message.id
+              );
+            }
+            const prev = state.messages[i - 1];
+            const previousAuthor = prev ? byId.get(prev.from) : void 0;
+            return /* @__PURE__ */ jsx(
+              Message,
+              {
+                theme,
+                message,
+                author,
+                previousAuthor
+              },
+              message.id
+            );
+          }),
+          state.typingIndicators.map((typing, i) => {
+            const author = byId.get(typing.from);
+            if (!author) return null;
+            return /* @__PURE__ */ jsx(
+              TypingIndicator,
+              {
+                theme,
+                typing,
+                author
+              },
+              `typing-${typing.from}-${i}`
+            );
+          })
+        ]
+      }
+    ),
+    composerAuthor ? /* @__PURE__ */ jsx(
+      Composer,
+      {
+        theme,
+        composer: state.composer,
+        author: composerAuthor
+      }
+    ) : null
+  ] }) });
+}
+function FitBox({
+  fit,
+  canvas,
+  children,
+  className,
+  style
+}) {
+  const ref = useRef(null);
+  const [container, setContainer] = useState(
+    null
+  );
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver((entries) => {
+      const rect = entries[0]?.contentRect;
+      if (rect) setContainer({ w: rect.width, h: rect.height });
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  if (fit === "reflow") {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref,
+        className,
+        "data-fit": "reflow",
+        style: { width: "100%", ...style },
+        children
+      }
+    );
+  }
+  if (fit === "fixed") {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref,
+        className,
+        "data-fit": "fixed",
+        style: {
+          width: canvas.width,
+          height: canvas.height,
+          overflow: "hidden",
+          ...style
+        },
+        children
+      }
+    );
+  }
+  const scale = container ? Math.min(container.w / canvas.width, container.h / canvas.height) : 1;
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref,
+      className,
+      "data-fit": "scale",
+      style: { width: "100%", height: "100%", overflow: "hidden", ...style },
+      children: /* @__PURE__ */ jsx(
+        "div",
+        {
+          "data-fit-canvas": "",
+          style: {
+            width: canvas.width,
+            height: canvas.height,
+            transform: `scale(${scale})`,
+            transformOrigin: "top left"
+          },
+          children
+        }
+      )
+    }
+  );
+}
+var SR_ONLY = {
+  position: "absolute",
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: "hidden",
+  clipPath: "inset(50%)",
+  whiteSpace: "nowrap",
+  border: 0
+};
+function Typecaast({
+  config,
+  skin,
+  theme,
+  autoplay,
+  loop,
+  rate,
+  fit,
+  label,
+  className,
+  style
+}) {
+  const reduced = useReducedMotion();
+  const tc = useTypecaast(config, {
+    theme,
+    autoplay: autoplay && !reduced,
+    loop: loop && !reduced,
+    rate,
+    capabilities: skin.meta.capabilities
+  });
+  const fonts = useSkinFonts(skin);
+  useEffect(() => {
+    if (reduced) tc.seek(tc.duration);
+  }, [reduced, tc]);
+  const transcript = useMemo(() => buildTranscript(config), [config]);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className,
+      style: { position: "relative", ...style },
+      "data-typecaast": "",
+      "data-fonts": fonts,
+      role: "figure",
+      "aria-label": label ?? `Chat simulation (${skin.meta.name})`,
+      children: [
+        /* @__PURE__ */ jsx("ol", { style: SR_ONLY, children: transcript.map((line, i) => /* @__PURE__ */ jsxs("li", { children: [
+          line.name,
+          ": ",
+          line.text
+        ] }, i)) }),
+        /* @__PURE__ */ jsx("div", { "aria-hidden": "true", style: { height: "100%" }, children: /* @__PURE__ */ jsx(FitBox, { fit: fit ?? config.meta.fit, canvas: config.meta.canvas, children: /* @__PURE__ */ jsx(
+          TypecaastStage,
+          {
+            state: tc.state,
+            skin,
+            participants: config.participants,
+            options: config.meta.skin.options
+          }
+        ) }) })
+      ]
+    }
+  );
+}
+
+// src/resolve-theme.ts
+function resolveTheme(mode) {
+  return mode === "dark" ? "dark" : mode === "light" ? "light" : "light";
+}
+
+export { FitBox, Typecaast, TypecaastStage, buildTranscript, resolveTheme, usePrefersDark, useReducedMotion, useResolvedTheme, useSkinFonts, useTypecaast };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map