@rettangoli/fe 1.2.1 → 1.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuusoft
+
+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

@@ -95,6 +95,7 @@ src/
 
 - `rtgl fe build` uses Vite 8's Rolldown-powered `vite.build()` with a virtual entry module generated from configured component files.
 - `rtgl fe watch` uses `vite.createServer()`, warms the virtual entry during startup, and serves the configured `outfile` path via middleware.
+- Watch projects can configure `fe.publicDir` to serve static assets from the project root without Vite transformations.
 - FE runtime source is generated in memory (virtual module), so no temporary generated JS files are required.
 - Contract validation, YAML parsing, and template parsing still run before code generation.
 - Component directories, setup files, and locale files are registered explicitly so watch mode also sees sources outside the served static root.
@@ -125,6 +126,7 @@ fe:
     - "./src/pages"
   setup: "setup.js"
   outfile: "./dist/bundle.js"
+  publicDir: "./static"
   i18n:
     dir: "./src/i18n"
     defaultLocale: "en"
@@ -136,6 +138,10 @@ fe:
     outputDir: "./vt/specs/examples"
 ```
 
+`publicDir` is optional and only affects `rtgl fe watch`. Its files are served
+at `/` without Vite transformations. This is useful for extensionless or other
+binary assets that must retain their source filenames.
+
 ## Setup Contract
 
 `setup.js` should export `deps` only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rettangoli/fe",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Frontend framework for building reactive web components",
   "type": "module",
   "main": "./src/index.js",
@@ -44,6 +44,7 @@
   "scripts": {
     "dev": "node ../rettangoli-cli/cli.js fe watch",
     "test": "vitest run --reporter=verbose",
+    "test:package": "node test/package-smoke-test.js",
     "test:puty": "vitest run puty.spec.js --reporter=verbose",
     "test:vitest": "vitest run test/**/*.test.js --reporter=verbose"
   }

package/src/cli/watch.js

@@ -43,13 +43,19 @@ export const createWatchServer = async (options = {}) => {
     outfile = "./vt/static/main.js",
     setup = "setup.js",
     i18n = null,
+    publicDir,
   } = options;
 
   const { root, publicEntryPath } = resolveServeContext({ cwd, outfile });
+  const resolvedPublicDir =
+    typeof publicDir === "string" && publicDir.length > 0
+      ? path.resolve(cwd, publicDir)
+      : publicDir;
 
   const server = await createServer({
     clearScreen: false,
     configFile: false,
+    publicDir: resolvedPublicDir,
     root,
     server: {
       port,

package/src/web/componentUpdateHook.js

@@ -1,42 +1,306 @@
 import { scheduleFrame } from "./scheduler.js";
 
+export const RETTANGOLI_COMPONENT_MARKER = Symbol.for(
+  "@rettangoli/fe/component",
+);
+
+const propsSnapshots = new WeakMap();
+const pendingUpdates = new WeakMap();
+
+const createReferenceSnapshot = (value) => ({
+  value,
+  hasStructuralSnapshot: false,
+});
+
+const hasUnsupportedToJSONOrPrototypeCycle = (value) => {
+  const visited = new Set();
+  let current = value;
+
+  while (current !== null) {
+    if (visited.has(current)) return true;
+    visited.add(current);
+
+    const descriptor = Object.getOwnPropertyDescriptor(current, "toJSON");
+    if (descriptor) {
+      if (!("value" in descriptor)) return true;
+      return typeof descriptor.value === "function";
+    }
+    current = Object.getPrototypeOf(current);
+  }
+
+  return false;
+};
+
+const isJsonData = (value, ancestors = new Set()) => {
+  if (value === null) return true;
+
+  const valueType = typeof value;
+  if (valueType === "string" || valueType === "boolean") return true;
+  if (valueType === "number") {
+    return Number.isFinite(value) && !Object.is(value, -0);
+  }
+  if (valueType !== "object") return false;
+
+  if (ancestors.has(value)) return false;
+
+  const isArray = Array.isArray(value);
+  const prototype = Object.getPrototypeOf(value);
+  if (
+    (isArray && prototype !== Array.prototype) ||
+    (!isArray && prototype !== Object.prototype && prototype !== null)
+  ) {
+    return false;
+  }
+
+  if (hasUnsupportedToJSONOrPrototypeCycle(value)) return false;
+
+  ancestors.add(value);
+  try {
+    if (isArray) {
+      const ownKeys = Reflect.ownKeys(value);
+      if (ownKeys.length !== value.length + 1 || !ownKeys.includes("length")) {
+        return false;
+      }
+
+      for (let index = 0; index < value.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(
+          value,
+          String(index),
+        );
+        if (
+          !descriptor ||
+          !("value" in descriptor) ||
+          !descriptor.enumerable ||
+          !isJsonData(descriptor.value, ancestors)
+        ) {
+          return false;
+        }
+      }
+
+      return true;
+    }
+
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== "string") return false;
+
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (
+        !descriptor ||
+        !("value" in descriptor) ||
+        !descriptor.enumerable ||
+        !isJsonData(descriptor.value, ancestors)
+      ) {
+        return false;
+      }
+    }
+
+    return true;
+  } finally {
+    ancestors.delete(value);
+  }
+};
+
+const createPropSnapshot = (value) => {
+  if (value === null || typeof value !== "object") {
+    return createReferenceSnapshot(value);
+  }
+
+  try {
+    if (!isJsonData(value)) {
+      return createReferenceSnapshot(value);
+    }
+
+    // Keep the live value for identity and a separate old value only for
+    // detecting and reporting same-reference JSON-data mutations.
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined || typeof structuredClone !== "function") {
+      return createReferenceSnapshot(value);
+    }
+    return {
+      value,
+      hasStructuralSnapshot: true,
+      serialized,
+      oldValue: structuredClone(value),
+    };
+  } catch {
+    return createReferenceSnapshot(value);
+  }
+};
+
+const createPropsSnapshot = (props = {}) => {
+  const entries = new Map();
+  Object.keys(props).forEach((key) => {
+    entries.set(key, createPropSnapshot(props[key]));
+  });
+  return entries;
+};
+
+const propChanged = (previousEntry, nextEntry) => {
+  if (!previousEntry || !nextEntry) return true;
+  if (previousEntry.hasStructuralSnapshot !== nextEntry.hasStructuralSnapshot) {
+    return true;
+  }
+  if (previousEntry.hasStructuralSnapshot) {
+    return previousEntry.serialized !== nextEntry.serialized;
+  }
+  return !Object.is(previousEntry.value, nextEntry.value);
+};
+
+const getChangedPropKeys = (previousSnapshot, nextSnapshot) => {
+  const keys = new Set([...previousSnapshot.keys(), ...nextSnapshot.keys()]);
+  return [...keys].filter((key) =>
+    propChanged(previousSnapshot.get(key), nextSnapshot.get(key)),
+  );
+};
+
+const defineProp = (target, key, value) => {
+  Object.defineProperty(target, key, {
+    configurable: true,
+    enumerable: true,
+    value,
+    writable: true,
+  });
+};
+
+const hasDriftedFromSnapshot = (entry) => {
+  if (!entry.hasStructuralSnapshot) return false;
+  try {
+    if (!isJsonData(entry.value)) return true;
+    return JSON.stringify(entry.value) !== entry.serialized;
+  } catch {
+    return true;
+  }
+};
+
+const createOldProps = (previousSnapshot) => {
+  const oldProps = {};
+  previousSnapshot.forEach((entry, key) => {
+    defineProp(
+      oldProps,
+      key,
+      hasDriftedFromSnapshot(entry) ? entry.oldValue : entry.value,
+    );
+  });
+  return oldProps;
+};
+
+const isRettangoliComponent = (element) => {
+  try {
+    if (element?.[RETTANGOLI_COMPONENT_MARKER] === true) {
+      return true;
+    }
+
+    // Compatibility for separately bundled components built before the brand
+    // existed. These relationships are installed together by the FE runtime.
+    return (
+      typeof element?.elementName === "string" &&
+      typeof element.render === "function" &&
+      typeof element.patch === "function" &&
+      typeof element._snabbdomH === "function" &&
+      element.deps?.render === element.render &&
+      element.deps?.store === element.store &&
+      element.deps?.props === element.props
+    );
+  } catch {
+    return false;
+  }
+};
+
+const storePropsSnapshot = (element, props = {}) => {
+  const snapshot = createPropsSnapshot(props);
+  propsSnapshots.set(element, snapshot);
+  return snapshot;
+};
+
+const runPendingUpdate = (element, pendingUpdate) => {
+  if (pendingUpdates.get(element) !== pendingUpdate) return;
+
+  pendingUpdates.delete(element);
+
+  // Prop values remain live references between the parent render and this
+  // frame. Refresh the latest snapshot so the stored baseline matches the
+  // value the child is about to render.
+  const nextSnapshot = createPropsSnapshot(pendingUpdate.newProps);
+  propsSnapshots.set(element, nextSnapshot);
+  const changedPropKeys = getChangedPropKeys(
+    pendingUpdate.previousSnapshot,
+    nextSnapshot,
+  );
+
+  if (changedPropKeys.length === 0) {
+    element.removeAttribute("isDirty");
+    return;
+  }
+
+  const previousProps = createOldProps(pendingUpdate.previousSnapshot);
+
+  element.render();
+  element.removeAttribute("isDirty");
+
+  if (element.handlers && element.handlers.handleOnUpdate) {
+    const deps = {
+      ...element.deps,
+      store: element.store,
+      render: element.render.bind(element),
+      handlers: element.handlers,
+      dispatchEvent: element.dispatchEvent.bind(element),
+      refs: element.refIds || {},
+    };
+    element.handlers.handleOnUpdate(deps, {
+      oldProps: previousProps,
+      newProps: pendingUpdate.newProps,
+    });
+  }
+};
+
 export const createWebComponentUpdateHook = ({
   scheduleFrameFn = scheduleFrame,
 } = {}) => {
   return {
+    insert: (vnode) => {
+      const element = vnode.elm;
+      if (!isRettangoliComponent(element)) return;
+      storePropsSnapshot(element, vnode.data?.props || {});
+    },
     update: (oldVnode, vnode) => {
+      const element = vnode.elm;
+      if (
+        !isRettangoliComponent(element) ||
+        typeof element.render !== "function"
+      ) {
+        return;
+      }
+
       const oldProps = oldVnode.data?.props || {};
       const newProps = vnode.data?.props || {};
+      const pendingUpdate = pendingUpdates.get(element);
 
-      const propsChanged = JSON.stringify(oldProps) !== JSON.stringify(newProps);
-      if (!propsChanged) {
+      if (pendingUpdate) {
+        pendingUpdate.newProps = newProps;
         return;
       }
 
-      const element = vnode.elm;
-      if (!element || typeof element.render !== "function") {
+      const previousSnapshot =
+        propsSnapshots.get(element) || createPropsSnapshot(oldProps);
+      const nextSnapshot = createPropsSnapshot(newProps);
+      const changedPropKeys = getChangedPropKeys(
+        previousSnapshot,
+        nextSnapshot,
+      );
+      if (changedPropKeys.length === 0) {
+        propsSnapshots.set(element, nextSnapshot);
         return;
       }
 
+      const nextPendingUpdate = {
+        previousSnapshot,
+        newProps,
+      };
+      pendingUpdates.set(element, nextPendingUpdate);
+
       element.setAttribute("isDirty", "true");
       scheduleFrameFn(() => {
-        element.render();
-        element.removeAttribute("isDirty");
-
-        if (element.handlers && element.handlers.handleOnUpdate) {
-          const deps = {
-            ...(element.deps),
-            store: element.store,
-            render: element.render.bind(element),
-            handlers: element.handlers,
-            dispatchEvent: element.dispatchEvent.bind(element),
-            refs: element.refIds || {},
-          };
-          element.handlers.handleOnUpdate(deps, {
-            oldProps,
-            newProps,
-          });
-        }
+        runPendingUpdate(element, nextPendingUpdate);
       });
     },
   };

package/src/web/createWebComponentClass.js

@@ -15,7 +15,10 @@ import {
   buildObservedAttributes,
 } from "../core/runtime/componentRuntime.js";
 import { initializeComponentDom } from "./componentDom.js";
-import { createWebComponentUpdateHook } from "./componentUpdateHook.js";
+import {
+  createWebComponentUpdateHook,
+  RETTANGOLI_COMPONENT_MARKER,
+} from "./componentUpdateHook.js";
 import { scheduleFrame } from "./scheduler.js";
 
 export const createWebComponentClass = ({
@@ -34,6 +37,7 @@ export const createWebComponentClass = ({
   deps,
 }) => {
   class BaseComponent extends HTMLElement {
+    [RETTANGOLI_COMPONENT_MARKER] = true;
     elementName;
     styles;
     _snabbdomH;