@renderify/ir 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Web LLM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @renderify/ir
+
+![Node CI](https://github.com/webllm/renderify/workflows/CI/badge.svg)
+![npm](https://img.shields.io/npm/v/@renderify/ir.svg)
+![license](https://img.shields.io/npm/l/@renderify/ir)
+
+Runtime IR contracts and utilities for Renderify.
+
+`@renderify/ir` defines the RuntimePlan schema, node/state/action types, guards, path helpers, import parsing, and shared constants used across all other packages.
+
+## Install
+
+```bash
+pnpm add @renderify/ir
+# or
+npm i @renderify/ir
+```
+
+## Main Exports
+
+- Types: `RuntimePlan`, `RuntimeNode`, `RuntimeCapabilities`, `RuntimeExecutionResult`, `RuntimeSourceModule`
+- Guards: `isRuntimePlan`, `isRuntimeNode`, `isJsonValue`
+- Builders: `createTextNode`, `createElementNode`, `createComponentNode`
+- Path utils: `getValueByPath`, `setValueByPath`, `isSafePath`
+- Import parsing: `collectRuntimeSourceImports`, `parseRuntimeSourceImportRanges`
+- Hash utils: `hashStringFNV1a32`, `createFnv1a64Hasher`
+- Shared constants: `DEFAULT_RUNTIME_PLAN_SPEC_VERSION`, `DEFAULT_JSPM_SPECIFIER_OVERRIDES`
+
+## Quick Start
+
+```ts
+import {
+  createElementNode,
+  createTextNode,
+  isRuntimePlan,
+  type RuntimePlan,
+} from "@renderify/ir";
+
+const plan: RuntimePlan = {
+  specVersion: "runtime-plan/v1",
+  id: "demo",
+  version: 1,
+  capabilities: { domWrite: true },
+  root: createElementNode("div", {}, [createTextNode("Hello Renderify")]),
+};
+
+if (!isRuntimePlan(plan)) {
+  throw new Error("Invalid RuntimePlan");
+}
+```
+
+## Notes
+
+- This package is framework-agnostic.
+- All other Renderify packages depend on these contracts.

package/dist/ir.cjs.js

@@ -0,0 +1,576 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  DEFAULT_JSPM_SPECIFIER_OVERRIDES: () => DEFAULT_JSPM_SPECIFIER_OVERRIDES,
+  DEFAULT_RUNTIME_PLAN_SPEC_VERSION: () => DEFAULT_RUNTIME_PLAN_SPEC_VERSION,
+  RUNTIME_PLAN_SPEC_VERSION_V1: () => RUNTIME_PLAN_SPEC_VERSION_V1,
+  asJsonValue: () => asJsonValue,
+  cloneJsonValue: () => cloneJsonValue,
+  collectComponentModules: () => collectComponentModules,
+  collectRuntimeSourceImports: () => collectRuntimeSourceImports,
+  createComponentNode: () => createComponentNode,
+  createElementNode: () => createElementNode,
+  createFnv1a64Hasher: () => createFnv1a64Hasher,
+  createTextNode: () => createTextNode,
+  getValueByPath: () => getValueByPath,
+  hashStringFNV1a32: () => hashStringFNV1a32,
+  hashStringFNV1a32Base36: () => hashStringFNV1a32Base36,
+  hashStringFNV1a64Hex: () => hashStringFNV1a64Hex,
+  isJsonValue: () => isJsonValue,
+  isRuntimeAction: () => isRuntimeAction,
+  isRuntimeCapabilities: () => isRuntimeCapabilities,
+  isRuntimeEvent: () => isRuntimeEvent,
+  isRuntimeModuleDescriptor: () => isRuntimeModuleDescriptor,
+  isRuntimeModuleManifest: () => isRuntimeModuleManifest,
+  isRuntimeNode: () => isRuntimeNode,
+  isRuntimePlan: () => isRuntimePlan,
+  isRuntimePlanMetadata: () => isRuntimePlanMetadata,
+  isRuntimeSourceLanguage: () => isRuntimeSourceLanguage,
+  isRuntimeSourceModule: () => isRuntimeSourceModule,
+  isRuntimeSourceRuntime: () => isRuntimeSourceRuntime,
+  isRuntimeStateModel: () => isRuntimeStateModel,
+  isRuntimeStateSnapshot: () => isRuntimeStateSnapshot,
+  isRuntimeValueFromPath: () => isRuntimeValueFromPath,
+  isSafePath: () => isSafePath,
+  parseRuntimeSourceImportRanges: () => parseRuntimeSourceImportRanges,
+  resolveRuntimePlanSpecVersion: () => resolveRuntimePlanSpecVersion,
+  setValueByPath: () => setValueByPath,
+  splitPath: () => splitPath,
+  walkRuntimeNode: () => walkRuntimeNode
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/hash.ts
+var FNV1A_64_OFFSET_BASIS = 0xcbf29ce484222325n;
+var FNV1A_64_PRIME = 0x100000001b3n;
+var UINT64_MASK = 0xffffffffffffffffn;
+function createFnv1a64Hasher() {
+  let hash = FNV1A_64_OFFSET_BASIS;
+  return {
+    update: (chunk) => {
+      for (let index = 0; index < chunk.length; index += 1) {
+        hash ^= BigInt(chunk.charCodeAt(index));
+        hash = hash * FNV1A_64_PRIME & UINT64_MASK;
+      }
+    },
+    digestHex: () => hash.toString(16)
+  };
+}
+function hashStringFNV1a64Hex(value) {
+  const hasher = createFnv1a64Hasher();
+  hasher.update(value);
+  return hasher.digestHex();
+}
+function hashStringFNV1a32(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+  }
+  return hash >>> 0;
+}
+function hashStringFNV1a32Base36(value) {
+  return hashStringFNV1a32(value).toString(36);
+}
+
+// src/source-imports.ts
+var import_es_module_lexer = require("es-module-lexer");
+var SOURCE_IMPORT_REWRITE_PATTERNS = [
+  /\bfrom\s+["']([^"']+)["']/g,
+  /\bimport\s+["']([^"']+)["']/g,
+  /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g
+];
+async function parseRuntimeSourceImportRanges(source) {
+  if (source.trim().length === 0) {
+    return [];
+  }
+  try {
+    await import_es_module_lexer.init;
+    const [imports] = (0, import_es_module_lexer.parse)(source);
+    const parsed = [];
+    for (const entry of imports) {
+      const specifier = entry.n?.trim();
+      if (!specifier) {
+        continue;
+      }
+      if (entry.s < 0 || entry.e <= entry.s) {
+        continue;
+      }
+      parsed.push({
+        start: entry.s,
+        end: entry.e,
+        specifier
+      });
+    }
+    return parsed.sort((left, right) => left.start - right.start);
+  } catch {
+    return parseRuntimeSourceImportRangesFromRegex(source);
+  }
+}
+async function collectRuntimeSourceImports(source) {
+  const ranges = await parseRuntimeSourceImportRanges(source);
+  const imports = /* @__PURE__ */ new Set();
+  for (const entry of ranges) {
+    imports.add(entry.specifier);
+  }
+  return [...imports];
+}
+function parseRuntimeSourceImportRangesFromRegex(source) {
+  const parsed = /* @__PURE__ */ new Map();
+  for (const pattern of SOURCE_IMPORT_REWRITE_PATTERNS) {
+    const regex = new RegExp(
+      pattern.source,
+      pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`
+    );
+    let match = regex.exec(source);
+    while (match) {
+      const fullMatch = String(match[0] ?? "");
+      const capturedSpecifier = String(match[1] ?? "").trim();
+      if (capturedSpecifier.length === 0) {
+        match = regex.exec(source);
+        continue;
+      }
+      const relativeIndex = fullMatch.indexOf(capturedSpecifier);
+      if (relativeIndex < 0) {
+        match = regex.exec(source);
+        continue;
+      }
+      const start = match.index + relativeIndex;
+      const end = start + capturedSpecifier.length;
+      parsed.set(`${start}:${end}`, {
+        start,
+        end,
+        specifier: capturedSpecifier
+      });
+      match = regex.exec(source);
+    }
+  }
+  return [...parsed.values()].sort((left, right) => left.start - right.start);
+}
+
+// src/index.ts
+var DEFAULT_JSPM_SPECIFIER_OVERRIDES = Object.freeze({
+  preact: "https://ga.jspm.io/npm:preact@10.28.3/dist/preact.module.js",
+  "preact/hooks": "https://ga.jspm.io/npm:preact@10.28.3/hooks/dist/hooks.module.js",
+  "preact/compat": "https://ga.jspm.io/npm:preact@10.28.3/compat/dist/compat.module.js",
+  "preact/jsx-runtime": "https://ga.jspm.io/npm:preact@10.28.3/jsx-runtime/dist/jsxRuntime.module.js",
+  react: "https://ga.jspm.io/npm:preact@10.28.3/compat/dist/compat.module.js",
+  "react-dom": "https://ga.jspm.io/npm:preact@10.28.3/compat/dist/compat.module.js",
+  "react-dom/client": "https://ga.jspm.io/npm:preact@10.28.3/compat/dist/compat.module.js",
+  "react/jsx-runtime": "https://ga.jspm.io/npm:preact@10.28.3/jsx-runtime/dist/jsxRuntime.module.js",
+  "react/jsx-dev-runtime": "https://ga.jspm.io/npm:preact@10.28.3/jsx-runtime/dist/jsxRuntime.module.js",
+  recharts: "https://ga.jspm.io/npm:recharts@3.3.0/es6/index.js"
+});
+var RUNTIME_PLAN_SPEC_VERSION_V1 = "runtime-plan/v1";
+var DEFAULT_RUNTIME_PLAN_SPEC_VERSION = RUNTIME_PLAN_SPEC_VERSION_V1;
+function createTextNode(value) {
+  return { type: "text", value };
+}
+function createElementNode(tag, props, children) {
+  return { type: "element", tag, props, children };
+}
+function createComponentNode(module2, exportName = "default", props, children) {
+  return { type: "component", module: module2, exportName, props, children };
+}
+function isRuntimeNode(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  if (candidate.type === "text") {
+    return typeof candidate.value === "string";
+  }
+  if (candidate.type === "element") {
+    return typeof candidate.tag === "string";
+  }
+  if (candidate.type === "component") {
+    return typeof candidate.module === "string";
+  }
+  return false;
+}
+function isJsonValue(value) {
+  return isJsonValueInternal(value, /* @__PURE__ */ new Set());
+}
+function isRuntimeValueFromPath(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.$from === "string";
+}
+function isRuntimeAction(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (typeof value.path !== "string" || value.path.trim().length === 0) {
+    return false;
+  }
+  if (value.type === "set" || value.type === "push") {
+    return "value" in value && (isJsonValue(value.value) || isRuntimeValueFromPath(value.value));
+  }
+  if (value.type === "increment") {
+    return value.by === void 0 || typeof value.by === "number" && Number.isFinite(value.by);
+  }
+  if (value.type === "toggle") {
+    return true;
+  }
+  return false;
+}
+function isRuntimeStateSnapshot(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  for (const entry of Object.values(value)) {
+    if (!isJsonValue(entry)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isRuntimeStateModel(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (!isRuntimeStateSnapshot(value.initial)) {
+    return false;
+  }
+  if (value.transitions === void 0) {
+    return true;
+  }
+  if (!isRecord(value.transitions)) {
+    return false;
+  }
+  for (const [eventType, actions] of Object.entries(value.transitions)) {
+    if (eventType.trim().length === 0) {
+      return false;
+    }
+    if (!Array.isArray(actions)) {
+      return false;
+    }
+    for (const action of actions) {
+      if (!isRuntimeAction(action)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+function isRuntimeCapabilities(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (value.domWrite !== void 0 && typeof value.domWrite !== "boolean") {
+    return false;
+  }
+  if (value.networkHosts !== void 0 && (!Array.isArray(value.networkHosts) || value.networkHosts.some((entry) => typeof entry !== "string"))) {
+    return false;
+  }
+  if (value.allowedModules !== void 0 && (!Array.isArray(value.allowedModules) || value.allowedModules.some((entry) => typeof entry !== "string"))) {
+    return false;
+  }
+  if (value.timers !== void 0 && typeof value.timers !== "boolean") {
+    return false;
+  }
+  if (value.executionProfile !== void 0 && value.executionProfile !== "standard" && value.executionProfile !== "isolated-vm" && value.executionProfile !== "sandbox-worker" && value.executionProfile !== "sandbox-iframe") {
+    return false;
+  }
+  if (value.storage !== void 0 && (!Array.isArray(value.storage) || value.storage.some(
+    (entry) => entry !== "localStorage" && entry !== "sessionStorage"
+  ))) {
+    return false;
+  }
+  if (!isFiniteNonNegativeNumber(value.maxImports)) {
+    return false;
+  }
+  if (!isFiniteNonNegativeNumber(value.maxComponentInvocations)) {
+    return false;
+  }
+  if (value.maxExecutionMs !== void 0 && (typeof value.maxExecutionMs !== "number" || !Number.isFinite(value.maxExecutionMs) || value.maxExecutionMs < 1)) {
+    return false;
+  }
+  return true;
+}
+function isRuntimeSourceLanguage(value) {
+  return value === "js" || value === "jsx" || value === "ts" || value === "tsx";
+}
+function isRuntimeSourceRuntime(value) {
+  return value === "renderify" || value === "preact";
+}
+function isRuntimeSourceModule(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (typeof value.code !== "string" || value.code.trim().length === 0) {
+    return false;
+  }
+  if (!isRuntimeSourceLanguage(value.language)) {
+    return false;
+  }
+  if (value.exportName !== void 0 && (typeof value.exportName !== "string" || value.exportName.trim().length === 0)) {
+    return false;
+  }
+  if (value.runtime !== void 0 && !isRuntimeSourceRuntime(value.runtime)) {
+    return false;
+  }
+  return true;
+}
+function isRuntimePlanMetadata(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (value.sourcePrompt !== void 0 && typeof value.sourcePrompt !== "string") {
+    return false;
+  }
+  if (value.sourceModel !== void 0 && typeof value.sourceModel !== "string") {
+    return false;
+  }
+  if (value.tags !== void 0 && (!Array.isArray(value.tags) || value.tags.some((entry) => typeof entry !== "string"))) {
+    return false;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === "sourcePrompt" || key === "sourceModel" || key === "tags") {
+      continue;
+    }
+    if (entry !== void 0 && !isJsonValue(entry)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isRuntimeEvent(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (typeof value.type !== "string" || value.type.trim().length === 0) {
+    return false;
+  }
+  if (value.payload !== void 0 && !isRuntimeStateSnapshot(value.payload)) {
+    return false;
+  }
+  return true;
+}
+function isRuntimePlan(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (typeof value.id !== "string" || value.id.trim().length === 0) {
+    return false;
+  }
+  if (typeof value.version !== "number" || !Number.isInteger(value.version) || value.version <= 0) {
+    return false;
+  }
+  if (!isRuntimeNode(value.root)) {
+    return false;
+  }
+  if (!isRuntimeCapabilities(value.capabilities)) {
+    return false;
+  }
+  if (value.specVersion !== void 0 && (typeof value.specVersion !== "string" || value.specVersion.trim().length === 0)) {
+    return false;
+  }
+  if (value.imports !== void 0 && (!Array.isArray(value.imports) || value.imports.some((entry) => typeof entry !== "string"))) {
+    return false;
+  }
+  if (value.moduleManifest !== void 0 && !isRuntimeModuleManifest(value.moduleManifest)) {
+    return false;
+  }
+  if (value.state !== void 0 && !isRuntimeStateModel(value.state)) {
+    return false;
+  }
+  if (value.source !== void 0 && !isRuntimeSourceModule(value.source)) {
+    return false;
+  }
+  if (value.metadata !== void 0 && !isRuntimePlanMetadata(value.metadata)) {
+    return false;
+  }
+  return true;
+}
+function isRuntimeModuleDescriptor(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (typeof value.resolvedUrl !== "string" || value.resolvedUrl.trim().length === 0) {
+    return false;
+  }
+  if (value.integrity !== void 0 && (typeof value.integrity !== "string" || value.integrity.trim().length === 0)) {
+    return false;
+  }
+  if (value.version !== void 0 && (typeof value.version !== "string" || value.version.trim().length === 0)) {
+    return false;
+  }
+  if (value.signer !== void 0 && (typeof value.signer !== "string" || value.signer.trim().length === 0)) {
+    return false;
+  }
+  return true;
+}
+function isRuntimeModuleManifest(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  for (const [specifier, descriptor] of Object.entries(value)) {
+    if (specifier.trim().length === 0) {
+      return false;
+    }
+    if (!isRuntimeModuleDescriptor(descriptor)) {
+      return false;
+    }
+  }
+  return true;
+}
+function resolveRuntimePlanSpecVersion(specVersion) {
+  if (typeof specVersion === "string" && specVersion.trim().length > 0) {
+    return specVersion.trim();
+  }
+  return DEFAULT_RUNTIME_PLAN_SPEC_VERSION;
+}
+function walkRuntimeNode(node, visitor, depth = 0) {
+  visitor(node, depth);
+  const children = node.type === "text" ? void 0 : node.children;
+  if (!children || children.length === 0) {
+    return;
+  }
+  for (const child of children) {
+    walkRuntimeNode(child, visitor, depth + 1);
+  }
+}
+function collectComponentModules(root) {
+  const modules = /* @__PURE__ */ new Set();
+  walkRuntimeNode(root, (node) => {
+    if (node.type === "component") {
+      modules.add(node.module);
+    }
+  });
+  return [...modules];
+}
+function splitPath(path) {
+  return path.split(".").map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+}
+function isSafePath(path) {
+  const segments = splitPath(path);
+  if (segments.length === 0) {
+    return false;
+  }
+  for (const segment of segments) {
+    if (segment === "__proto__" || segment === "prototype" || segment === "constructor") {
+      return false;
+    }
+  }
+  return true;
+}
+function getValueByPath(source, path) {
+  const segments = splitPath(path);
+  if (segments.length === 0) {
+    return void 0;
+  }
+  let cursor = source;
+  for (const segment of segments) {
+    if (typeof cursor !== "object" || cursor === null) {
+      return void 0;
+    }
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function setValueByPath(target, path, value) {
+  const segments = splitPath(path);
+  if (segments.length === 0) {
+    return;
+  }
+  let cursor = target;
+  for (let i = 0; i < segments.length; i += 1) {
+    const segment = segments[i];
+    const isLast = i === segments.length - 1;
+    if (isLast) {
+      cursor[segment] = value;
+      return;
+    }
+    const next = cursor[segment];
+    if (typeof next !== "object" || next === null || Array.isArray(next)) {
+      cursor[segment] = {};
+    }
+    cursor = cursor[segment];
+  }
+}
+function cloneJsonValue(value) {
+  if (typeof globalThis.structuredClone === "function") {
+    return globalThis.structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+function asJsonValue(value) {
+  if (value === void 0) {
+    return null;
+  }
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => asJsonValue(item));
+  }
+  if (typeof value === "object" && value !== null) {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+      result[key] = asJsonValue(item);
+    }
+    return result;
+  }
+  return String(value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFiniteNonNegativeNumber(value) {
+  return value === void 0 || typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isJsonValueInternal(value, seen) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return true;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value);
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      return false;
+    }
+    seen.add(value);
+    const valid = value.every((entry) => isJsonValueInternal(entry, seen));
+    seen.delete(value);
+    return valid;
+  }
+  if (isRecord(value)) {
+    if (seen.has(value)) {
+      return false;
+    }
+    seen.add(value);
+    const valid = Object.values(value).every(
+      (entry) => isJsonValueInternal(entry, seen)
+    );
+    seen.delete(value);
+    return valid;
+  }
+  return false;
+}
+//# sourceMappingURL=ir.cjs.js.map