embedded-react 0.4.0 → 0.5.0

package/aot/compile.mjs

@@ -879,7 +879,11 @@ function collectSvgImports(program) {
  *  @param {string} baseDir   Directory the import paths are resolved against (the app's dir).
  *  @returns {Promise<Object>} name → { ops, paints, gradients, width, height }. */
 export async function bakeSvgArtifacts(src, baseDir) {
-  const program = parse(src, {sourceType: 'module', plugins: ['jsx']}).program;
+  // Parse with the TS plugin too (harmless for plain JSX) so a .tsx app's <Svg source> imports are found.
+  const program = parse(src, {
+    sourceType: 'module',
+    plugins: ['jsx', 'typescript'],
+  }).program;
   const imports = collectSvgImports(program);
   if (imports.size === 0) return {};
   const {svgToVector, svgToRaster, writeRasterPng} =
@@ -4285,14 +4289,126 @@ function compileKeyboardConfig(program, out) {
 // directly; the CLI entry at the bottom of the file wraps it with the file read/write.
 // ---------------------------------------------------------------------------------------------------
 
+// --- TypeScript support (Flow B) ---------------------------------------------------------------------
+// The compiler walks a plain JS+JSX AST. TypeScript apps (App.tsx) parse with the `typescript` plugin and
+// are then scrubbed of all type-only syntax IN PLACE before the walker runs: the runtime nodes keep their
+// original source locations, so code-frame errors still point at the user's real source. This is a faithful
+// type strip — the generated C for an App.tsx is identical to its untyped App.jsx twin.
+
+/** Is this app a TypeScript entry? Driven by the filename extension, or an explicit opts.ts (for tests). */
+const isTsEntry = opts => opts.ts ?? /\.[cm]?tsx$/.test(opts.filename || '');
+
+const parserPlugins = ts => (ts ? ['jsx', 'typescript'] : ['jsx']);
+// Type-only expression wrappers: `x as T`, `x satisfies T`, `x!`, `<T>x`, `f<T>` — unwrap to the inner expr.
+const TS_EXPR_WRAPPERS = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSNonNullExpression',
+  'TSTypeAssertion',
+  'TSInstantiationExpression',
+]);
+// Type-only declarations (no runtime presence) — dropped from any statement/body list.
+const TS_TYPE_DECLS = new Set([
+  'TSInterfaceDeclaration',
+  'TSTypeAliasDeclaration',
+  'TSDeclareFunction',
+]);
+// Type-only fields hung off otherwise-runtime nodes — deleted so nothing downstream traverses into them.
+const TS_TYPE_FIELDS = [
+  'typeAnnotation',
+  'returnType',
+  'typeParameters',
+  'typeArguments',
+  'accessibility',
+  'definite',
+  'declare',
+  'readonly',
+  'override',
+  'abstract',
+];
+// Keys that never hold child AST nodes — skip them so the scrub stays cheap and never mangles metadata.
+const TS_SKIP_KEYS = new Set([
+  'loc',
+  'start',
+  'end',
+  'range',
+  'leadingComments',
+  'trailingComments',
+  'innerComments',
+  'comments',
+  'extra',
+  'tokens',
+]);
+
+/** True for nodes that carry no runtime meaning and must be removed from a statement/specifier list. */
+const isTypeOnly = node =>
+  !!node &&
+  (TS_TYPE_DECLS.has(node.type) ||
+    // `import type ... ` / `export type ...`, and per-specifier `import { type X }`.
+    ((node.type === 'ImportDeclaration' || node.type === 'ImportSpecifier') &&
+      node.importKind === 'type') ||
+    ((node.type === 'ExportNamedDeclaration' ||
+      node.type === 'ExportSpecifier') &&
+      node.exportKind === 'type'));
+
+/** Follow a chain of type-only expression wrappers to the runtime expression underneath. */
+const unwrapTs = node => {
+  while (node && TS_EXPR_WRAPPERS.has(node.type)) node = node.expression;
+  return node;
+};
+
+/**
+ * Strip every TypeScript-only construct from a parsed AST, in place: drop type declarations and type
+ * imports, unwrap `as`/`!`/`<T>` expression wrappers, and delete type-annotation fields. Remaining nodes
+ * keep their .loc, so the compiler's error code-frames stay accurate.
+ */
+function stripTypeScript(root) {
+  const visit = node => {
+    if (!node || typeof node !== 'object') return;
+    for (const f of TS_TYPE_FIELDS) if (f in node) delete node[f];
+    for (const key of Object.keys(node)) {
+      if (TS_SKIP_KEYS.has(key)) continue;
+      let val = node[key];
+      if (Array.isArray(val)) {
+        const kept = [];
+        for (let el of val) {
+          if (isTypeOnly(el)) continue;
+          if (el && TS_EXPR_WRAPPERS.has(el.type)) el = unwrapTs(el);
+          kept.push(el);
+          visit(el);
+        }
+        node[key] = kept;
+      } else if (val && typeof val.type === 'string') {
+        if (TS_EXPR_WRAPPERS.has(val.type)) {
+          val = unwrapTs(val);
+          node[key] = val;
+        }
+        visit(val);
+      } else if (val && typeof val === 'object') {
+        visit(val);
+      }
+    }
+  };
+  visit(root);
+  return root;
+}
+
+/** Parse an app entry to a JS+JSX AST, transparently stripping TypeScript when the entry is .ts/.tsx. */
+function parseApp(src, opts = {}) {
+  const ts = isTsEntry(opts);
+  const ast = parse(src, {sourceType: 'module', plugins: parserPlugins(ts)});
+  if (ts) stripTypeScript(ast);
+  return ast;
+}
+
 /**
- * Compiles a Flow B app's JSX source to C.
- * @param {string} src   The App.jsx source text.
+ * Compiles a Flow B app's JSX (or TSX) source to C.
+ * @param {string} src   The App.jsx/App.tsx source text.
  * @param {string} demo  Demo name (only used in the generated-by header comment).
  * @returns {{c: string, h: string, nodes: number, state: number, handlers: number, updates: number}}
  */
 function compileSourceImpl(src, demo = 'app', opts = {}) {
-  const ast = parse(src, {sourceType: 'module', plugins: ['jsx']});
+  const ast = parseApp(src, opts);
 
   const screen = opts.screen ?? {width: SCREEN_W, height: SCREEN_H};
   // Image imports first, so their asset-name strings seed the module scope BEFORE its consts fold (a const

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "embedded-react",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "React Native-style component package + reconciler that drives the embedded-react C engine through the QuickJS NativeUI bridge (Flow A).",
   "license": "Apache-2.0",
@@ -31,8 +31,12 @@
   "engines": {
     "node": ">=18"
   },
+  "types": "./src/embedded-react/index.d.ts",
   "exports": {
-    ".": "./src/embedded-react/index.js"
+    ".": {
+      "types": "./src/embedded-react/index.d.ts",
+      "default": "./src/embedded-react/index.js"
+    }
   },
   "bin": {
     "embedded-react": "cli.mjs"
@@ -71,6 +75,7 @@
     "test:watch": "vitest",
     "test:runtime": "node test/runtime/run.mjs",
     "test:bytecode": "node test/runtime/run.mjs --bytecode",
+    "typecheck": "tsc -p tsconfig.types.json",
     "format": "cd ../../.. && prettier --write \"**/*.{js,jsx,mjs,cjs}\"",
     "format:check": "cd ../../.. && prettier --check \"**/*.{js,jsx,mjs,cjs}\""
   },
@@ -86,7 +91,9 @@
     "svgson": "^5.3.1"
   },
   "devDependencies": {
+    "@types/react": "18.3.1",
     "prettier": "^3.4.2",
+    "typescript": "^5.5.0",
     "vitest": "^3.2.4"
   },
   "overrides": {

package/persist-transform.mjs

@@ -120,18 +120,31 @@ export function shouldPersist(absPath, projectRootNorm) {
 /**
  * Applies the persist transform to a module's source.
  *
- * @param {string} code      Module source (JSX allowed).
+ * TypeScript entries (.ts/.tsx) are parsed with the `typescript` plugin enabled; the type syntax is
+ * preserved in the output and stripped downstream by esbuild's ts/tsx loader (see sim-server.mjs).
+ *
+ * @param {string} code      Module source (JSX and/or TypeScript allowed).
  * @param {string} moduleId  Stable module identifier (used in keys; e.g. a path relative to the app).
- * @returns {string} Transformed source (JSX preserved for esbuild to handle).
+ * @returns {string} Transformed source (JSX/TS preserved for esbuild to handle).
  */
 export function transformPersist(code, moduleId) {
+  // Enable the babel parser plugins this module's extension needs. `.tsx` is jsx+typescript; `.ts` is
+  // typescript-only (the jsx plugin would misparse `<T>` type assertions); everything else is jsx.
+  const isTs = /\.tsx?$/.test(moduleId);
+  const isTsx = /\.tsx$/.test(moduleId);
+  const parserPlugins = isTsx
+    ? ['jsx', 'typescript']
+    : isTs
+      ? ['typescript']
+      : ['jsx'];
   const out = transformSync(code, {
     filename: moduleId,
     babelrc: false,
     configFile: false,
     sourceType: 'module',
-    parserOpts: {plugins: ['jsx']},
-    plugins: [syntaxJsx, [persistPlugin, {moduleId}]],
+    parserOpts: {plugins: parserPlugins},
+    // syntaxJsx only enables jsx parsing; for ts/tsx we drive the parser via parserOpts above instead.
+    plugins: [...(isTs ? [] : [syntaxJsx]), [persistPlugin, {moduleId}]],
   });
   return out.code;
 }

package/sim-server.mjs

@@ -177,12 +177,19 @@ function createBundle({
             // node_modules is what stops the library's usePersistentState being rewritten to call itself).
             if (!persist || !shouldPersist(a.path, projNorm)) return undefined;
             try {
+              // Match the esbuild loader to the source extension so TS type syntax (preserved by the
+              // persist transform) is stripped: .tsx → tsx, .ts → ts, .jsx/.js → jsx.
+              const loader = a.path.endsWith('.tsx')
+                ? 'tsx'
+                : a.path.endsWith('.ts')
+                  ? 'ts'
+                  : 'jsx';
               return {
                 contents: transformPersist(
                   readFileSync(a.path, 'utf8'),
                   relative(projectRoot, a.path).replace(/\\/g, '/'),
                 ),
-                loader: 'jsx',
+                loader,
               };
             } catch (e) {
               return {errors: [{text: `persist transform: ${e.message}`}]};

package/src/embedded-react/index.d.ts

@@ -0,0 +1,211 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Public type declarations for the `embedded-react` package — the React Native analog. These cover the
+// common surface (View / Text / Pressable / Image / StyleSheet / Animated / hooks); the SVG primitives are
+// typed loosely for now. The runtime is JavaScript and ignores types entirely — these only power editors
+// and `tsc`. React hooks (useState, useEffect, …) still come from 'react', as in React Native.
+
+import type {ReactNode} from 'react';
+
+// --- Styling ---------------------------------------------------------------
+/** A single style object. Properties mirror the React Native subset the engine supports. */
+export interface ViewStyle {
+  [key: string]: string | number | undefined | TransformStyle[];
+  flex?: number;
+  flexDirection?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
+  alignItems?: 'flex-start' | 'flex-end' | 'center' | 'stretch';
+  justifyContent?:
+    | 'flex-start'
+    | 'flex-end'
+    | 'center'
+    | 'space-between'
+    | 'space-around'
+    | 'space-evenly';
+  width?: number | string;
+  height?: number | string;
+  maxWidth?: number | string;
+  maxHeight?: number | string;
+  margin?: number;
+  marginTop?: number;
+  marginBottom?: number;
+  marginLeft?: number;
+  marginRight?: number;
+  padding?: number;
+  paddingVertical?: number;
+  paddingHorizontal?: number;
+  gap?: number;
+  backgroundColor?: string;
+  borderRadius?: number;
+  borderWidth?: number;
+  borderColor?: string;
+  opacity?: number;
+  transform?: TransformStyle[];
+}
+
+export interface TextStyle extends ViewStyle {
+  color?: string;
+  fontSize?: number;
+  fontFamily?: string;
+  fontWeight?: string | number;
+  textAlign?: 'auto' | 'left' | 'right' | 'center';
+}
+
+export type TransformStyle =
+  | {scale: number | AnimatedValue}
+  | {scaleX: number | AnimatedValue}
+  | {scaleY: number | AnimatedValue}
+  | {translateX: number | AnimatedValue}
+  | {translateY: number | AnimatedValue}
+  | {rotate: string | AnimatedValue};
+
+export type StyleProp<T> = T | false | null | undefined | StyleProp<T>[];
+
+// --- Components ------------------------------------------------------------
+export interface ViewProps {
+  style?: StyleProp<ViewStyle>;
+  children?: ReactNode;
+}
+
+export interface TextProps {
+  style?: StyleProp<TextStyle>;
+  children?: ReactNode;
+  numberOfLines?: number;
+}
+
+export interface PressableProps {
+  style?: StyleProp<ViewStyle>;
+  children?: ReactNode;
+  onPress?: () => void;
+  disabled?: boolean;
+}
+
+export type ImageSource = number | string | {uri: string};
+
+export interface ImageProps {
+  source: ImageSource;
+  style?: StyleProp<ViewStyle>;
+}
+
+export interface ScrollViewProps extends ViewProps {
+  horizontal?: boolean;
+}
+
+export interface TextInputProps {
+  style?: StyleProp<TextStyle>;
+  value?: string;
+  placeholder?: string;
+  onChangeText?: (text: string) => void;
+}
+
+export interface SwitchProps {
+  value?: boolean;
+  onValueChange?: (value: boolean) => void;
+}
+
+export const View: (props: ViewProps) => JSX.Element;
+export const Text: (props: TextProps) => JSX.Element;
+export const Image: (props: ImageProps) => JSX.Element;
+export const Pressable: (props: PressableProps) => JSX.Element;
+export const TouchableOpacity: (props: PressableProps) => JSX.Element;
+export const ScrollView: (props: ScrollViewProps) => JSX.Element;
+export const FlatList: (props: Record<string, unknown>) => JSX.Element;
+export const TextInput: (props: TextInputProps) => JSX.Element;
+export const Switch: (props: SwitchProps) => JSX.Element;
+export const ActivityIndicator: (props: ViewProps) => JSX.Element;
+export const Modal: (props: ViewProps) => JSX.Element;
+
+// SVG primitives (see the repo for their full prop sets).
+export const Svg: (props: Record<string, unknown>) => JSX.Element;
+export const Path: (props: Record<string, unknown>) => JSX.Element;
+export const Circle: (props: Record<string, unknown>) => JSX.Element;
+export const Ellipse: (props: Record<string, unknown>) => JSX.Element;
+export const Rect: (props: Record<string, unknown>) => JSX.Element;
+export const Line: (props: Record<string, unknown>) => JSX.Element;
+export const G: (props: Record<string, unknown>) => JSX.Element;
+export const Arc: (props: Record<string, unknown>) => JSX.Element;
+
+// --- StyleSheet ------------------------------------------------------------
+export const StyleSheet: {
+  create<T extends Record<string, ViewStyle | TextStyle>>(styles: T): T;
+};
+
+// --- Platform --------------------------------------------------------------
+export const Platform: {
+  OS: string;
+  select<T>(specifics: Record<string, T>): T | undefined;
+};
+
+// --- AppRegistry -----------------------------------------------------------
+export const AppRegistry: {
+  registerComponent(
+    appKey: string,
+    componentProvider: () => (props: any) => JSX.Element,
+  ): void;
+};
+
+// --- Animated --------------------------------------------------------------
+// A handle to an engine-side animated float. Not importable directly — obtain one from `useAnimatedValue`
+// or `new Animated.Value(...)`, so this is a type, not a runtime export.
+export interface AnimatedValue {
+  setValue(value: number): void;
+  interpolate(config: {
+    inputRange: number[];
+    outputRange: number[] | string[];
+  }): AnimatedValue;
+}
+
+export interface AnimationConfig {
+  toValue: number;
+  duration?: number;
+  delay?: number;
+  easing?: (t: number) => number;
+  useNativeDriver?: boolean;
+}
+
+export interface Animation {
+  start(callback?: (result: {finished: boolean}) => void): void;
+  stop?(): void;
+}
+
+export const Animated: {
+  Value: new (initial?: number) => AnimatedValue;
+  View: (props: ViewProps) => JSX.Element;
+  Text: (props: TextProps) => JSX.Element;
+  Image: (props: ImageProps) => JSX.Element;
+  timing(value: AnimatedValue, config: AnimationConfig): Animation;
+  spring(value: AnimatedValue, config: AnimationConfig): Animation;
+  decay(value: AnimatedValue, config: Record<string, unknown>): Animation;
+  sequence(animations: Animation[]): Animation;
+  parallel(animations: Animation[], config?: {stopTogether?: boolean}): Animation;
+  stagger(delay: number, animations: Animation[]): Animation;
+  loop(animation: Animation, config?: {iterations?: number}): Animation;
+  delay(ms: number): Animation;
+};
+
+/** Creates an AnimatedValue tied to the component lifecycle (destroyed on unmount). */
+export function useAnimatedValue(initial?: number): AnimatedValue;
+
+/** Like useState, but the value survives a dev hot reload. */
+export function usePersistentState<S>(
+  initialState: S | (() => S),
+): [S, (value: S | ((prev: S) => S)) => void];
+
+export const Easing: Record<string, (t: number) => number>;
+export const LayoutAnimation: Record<string, unknown>;
+export function updateVector(...args: unknown[]): void;
+export function updateText(...args: unknown[]): void;
+export function setKeyboardConfig(...args: unknown[]): void;