@fictjs/runtime 0.0.2

package/src/constants.ts

@@ -0,0 +1,456 @@
+/**
+ * Fict DOM Constants
+ *
+ * Property constants and configurations for DOM attribute handling.
+ * Borrowed from dom-expressions for comprehensive DOM support.
+ */
+
+// ============================================================================
+// Boolean Attributes
+// ============================================================================
+
+/**
+ * Complete list of boolean attributes (lowercase)
+ * These attributes are set as empty strings when true, removed when false
+ */
+const booleans = [
+  'allowfullscreen',
+  'async',
+  'alpha', // HTMLInputElement
+  'autofocus', // HTMLElement prop
+  'autoplay',
+  'checked',
+  'controls',
+  'default',
+  'disabled',
+  'formnovalidate',
+  'hidden', // HTMLElement prop
+  'indeterminate',
+  'inert', // HTMLElement prop
+  'ismap',
+  'loop',
+  'multiple',
+  'muted',
+  'nomodule',
+  'novalidate',
+  'open',
+  'playsinline',
+  'readonly',
+  'required',
+  'reversed',
+  'seamless', // HTMLIframeElement - non-standard
+  'selected',
+  // Experimental attributes
+  'adauctionheaders',
+  'browsingtopics',
+  'credentialless',
+  'defaultchecked',
+  'defaultmuted',
+  'defaultselected',
+  'defer',
+  'disablepictureinpicture',
+  'disableremoteplayback',
+  'preservespitch',
+  'shadowrootclonable',
+  'shadowrootcustomelementregistry',
+  'shadowrootdelegatesfocus',
+  'shadowrootserializable',
+  'sharedstoragewritable',
+] as const
+
+export const BooleanAttributes = new Set<string>(booleans)
+
+// ============================================================================
+// Properties Set
+// ============================================================================
+
+/**
+ * Properties that should be set via DOM property (not attribute)
+ * Includes camelCase versions of boolean attributes
+ */
+export const Properties = new Set<string>([
+  // Core properties
+  'className',
+  'value',
+
+  // CamelCase booleans
+  'readOnly',
+  'noValidate',
+  'formNoValidate',
+  'isMap',
+  'noModule',
+  'playsInline',
+
+  // Experimental (camelCase)
+  'adAuctionHeaders',
+  'allowFullscreen',
+  'browsingTopics',
+  'defaultChecked',
+  'defaultMuted',
+  'defaultSelected',
+  'disablePictureInPicture',
+  'disableRemotePlayback',
+  'preservesPitch',
+  'shadowRootClonable',
+  'shadowRootCustomElementRegistry',
+  'shadowRootDelegatesFocus',
+  'shadowRootSerializable',
+  'sharedStorageWritable',
+
+  // All lowercase booleans
+  ...booleans,
+])
+
+// ============================================================================
+// Child Properties
+// ============================================================================
+
+/**
+ * Properties that represent children/content
+ */
+export const ChildProperties = new Set<string>([
+  'innerHTML',
+  'textContent',
+  'innerText',
+  'children',
+])
+
+// ============================================================================
+// Property Aliases
+// ============================================================================
+
+/**
+ * React compatibility aliases (className -> class)
+ */
+export const Aliases: Record<string, string> = {
+  className: 'class',
+  htmlFor: 'for',
+}
+
+/**
+ * Element-specific property aliases
+ * Maps lowercase attribute names to their camelCase property equivalents
+ * Only for specific elements that have these properties
+ */
+export const PropAliases: Record<
+  string,
+  string | { $: string; [tagName: string]: string | number }
+> = {
+  // Direct mapping
+  class: 'className',
+
+  // Element-specific mappings
+  novalidate: {
+    $: 'noValidate',
+    FORM: 1,
+  },
+  formnovalidate: {
+    $: 'formNoValidate',
+    BUTTON: 1,
+    INPUT: 1,
+  },
+  ismap: {
+    $: 'isMap',
+    IMG: 1,
+  },
+  nomodule: {
+    $: 'noModule',
+    SCRIPT: 1,
+  },
+  playsinline: {
+    $: 'playsInline',
+    VIDEO: 1,
+  },
+  readonly: {
+    $: 'readOnly',
+    INPUT: 1,
+    TEXTAREA: 1,
+  },
+
+  // Experimental element-specific
+  adauctionheaders: {
+    $: 'adAuctionHeaders',
+    IFRAME: 1,
+  },
+  allowfullscreen: {
+    $: 'allowFullscreen',
+    IFRAME: 1,
+  },
+  browsingtopics: {
+    $: 'browsingTopics',
+    IMG: 1,
+  },
+  defaultchecked: {
+    $: 'defaultChecked',
+    INPUT: 1,
+  },
+  defaultmuted: {
+    $: 'defaultMuted',
+    AUDIO: 1,
+    VIDEO: 1,
+  },
+  defaultselected: {
+    $: 'defaultSelected',
+    OPTION: 1,
+  },
+  disablepictureinpicture: {
+    $: 'disablePictureInPicture',
+    VIDEO: 1,
+  },
+  disableremoteplayback: {
+    $: 'disableRemotePlayback',
+    AUDIO: 1,
+    VIDEO: 1,
+  },
+  preservespitch: {
+    $: 'preservesPitch',
+    AUDIO: 1,
+    VIDEO: 1,
+  },
+  shadowrootclonable: {
+    $: 'shadowRootClonable',
+    TEMPLATE: 1,
+  },
+  shadowrootdelegatesfocus: {
+    $: 'shadowRootDelegatesFocus',
+    TEMPLATE: 1,
+  },
+  shadowrootserializable: {
+    $: 'shadowRootSerializable',
+    TEMPLATE: 1,
+  },
+  sharedstoragewritable: {
+    $: 'sharedStorageWritable',
+    IFRAME: 1,
+    IMG: 1,
+  },
+}
+
+/**
+ * Get the property alias for a given attribute and tag name
+ */
+export function getPropAlias(prop: string, tagName: string): string | undefined {
+  const a = PropAliases[prop]
+  if (typeof a === 'object') {
+    return a[tagName] ? a['$'] : undefined
+  }
+  return a
+}
+
+// ============================================================================
+// Event Delegation
+// ============================================================================
+
+/**
+ * Symbol for storing delegated events on the document
+ */
+export const $$EVENTS = '_$FICT_DELEGATE'
+
+/**
+ * Events that should use event delegation for performance
+ * These events bubble and are commonly used across many elements
+ */
+export const DelegatedEvents = new Set<string>([
+  'beforeinput',
+  'click',
+  'dblclick',
+  'contextmenu',
+  'focusin',
+  'focusout',
+  'input',
+  'keydown',
+  'keyup',
+  'mousedown',
+  'mousemove',
+  'mouseout',
+  'mouseover',
+  'mouseup',
+  'pointerdown',
+  'pointermove',
+  'pointerout',
+  'pointerover',
+  'pointerup',
+  'touchend',
+  'touchmove',
+  'touchstart',
+])
+
+// ============================================================================
+// SVG Support
+// ============================================================================
+
+/**
+ * SVG element names (excluding common ones that overlap with HTML)
+ */
+export const SVGElements = new Set<string>([
+  'altGlyph',
+  'altGlyphDef',
+  'altGlyphItem',
+  'animate',
+  'animateColor',
+  'animateMotion',
+  'animateTransform',
+  'circle',
+  'clipPath',
+  'color-profile',
+  'cursor',
+  'defs',
+  'desc',
+  'ellipse',
+  'feBlend',
+  'feColorMatrix',
+  'feComponentTransfer',
+  'feComposite',
+  'feConvolveMatrix',
+  'feDiffuseLighting',
+  'feDisplacementMap',
+  'feDistantLight',
+  'feDropShadow',
+  'feFlood',
+  'feFuncA',
+  'feFuncB',
+  'feFuncG',
+  'feFuncR',
+  'feGaussianBlur',
+  'feImage',
+  'feMerge',
+  'feMergeNode',
+  'feMorphology',
+  'feOffset',
+  'fePointLight',
+  'feSpecularLighting',
+  'feSpotLight',
+  'feTile',
+  'feTurbulence',
+  'filter',
+  'font',
+  'font-face',
+  'font-face-format',
+  'font-face-name',
+  'font-face-src',
+  'font-face-uri',
+  'foreignObject',
+  'g',
+  'glyph',
+  'glyphRef',
+  'hkern',
+  'image',
+  'line',
+  'linearGradient',
+  'marker',
+  'mask',
+  'metadata',
+  'missing-glyph',
+  'mpath',
+  'path',
+  'pattern',
+  'polygon',
+  'polyline',
+  'radialGradient',
+  'rect',
+  'set',
+  'stop',
+  'svg',
+  'switch',
+  'symbol',
+  'text',
+  'textPath',
+  'tref',
+  'tspan',
+  'use',
+  'view',
+  'vkern',
+])
+
+/**
+ * SVG attribute namespaces
+ */
+export const SVGNamespace: Record<string, string> = {
+  xlink: 'http://www.w3.org/1999/xlink',
+  xml: 'http://www.w3.org/XML/1998/namespace',
+}
+
+// ============================================================================
+// Unitless CSS Properties
+// ============================================================================
+
+/**
+ * CSS properties that don't need a unit (like 'px')
+ */
+export const UnitlessStyles = new Set<string>([
+  'animationIterationCount',
+  'animation-iteration-count',
+  'borderImageOutset',
+  'border-image-outset',
+  'borderImageSlice',
+  'border-image-slice',
+  'borderImageWidth',
+  'border-image-width',
+  'boxFlex',
+  'box-flex',
+  'boxFlexGroup',
+  'box-flex-group',
+  'boxOrdinalGroup',
+  'box-ordinal-group',
+  'columnCount',
+  'column-count',
+  'columns',
+  'flex',
+  'flexGrow',
+  'flex-grow',
+  'flexPositive',
+  'flex-positive',
+  'flexShrink',
+  'flex-shrink',
+  'flexNegative',
+  'flex-negative',
+  'flexOrder',
+  'flex-order',
+  'gridRow',
+  'grid-row',
+  'gridRowEnd',
+  'grid-row-end',
+  'gridRowSpan',
+  'grid-row-span',
+  'gridRowStart',
+  'grid-row-start',
+  'gridColumn',
+  'grid-column',
+  'gridColumnEnd',
+  'grid-column-end',
+  'gridColumnSpan',
+  'grid-column-span',
+  'gridColumnStart',
+  'grid-column-start',
+  'fontWeight',
+  'font-weight',
+  'lineClamp',
+  'line-clamp',
+  'lineHeight',
+  'line-height',
+  'opacity',
+  'order',
+  'orphans',
+  'tabSize',
+  'tab-size',
+  'widows',
+  'zIndex',
+  'z-index',
+  'zoom',
+  'fillOpacity',
+  'fill-opacity',
+  'floodOpacity',
+  'flood-opacity',
+  'stopOpacity',
+  'stop-opacity',
+  'strokeDasharray',
+  'stroke-dasharray',
+  'strokeDashoffset',
+  'stroke-dashoffset',
+  'strokeMiterlimit',
+  'stroke-miterlimit',
+  'strokeOpacity',
+  'stroke-opacity',
+  'strokeWidth',
+  'stroke-width',
+])

package/src/cycle-guard.ts

@@ -0,0 +1,134 @@
+import { getDevtoolsHook } from './devtools'
+
+export interface CycleProtectionOptions {
+  maxFlushCyclesPerMicrotask?: number
+  maxEffectRunsPerFlush?: number
+  windowSize?: number
+  highUsageRatio?: number
+  maxRootReentrantDepth?: number
+  enableWindowWarning?: boolean
+  devMode?: boolean
+}
+
+interface CycleWindowEntry {
+  used: number
+  budget: number
+}
+
+const defaultOptions = {
+  maxFlushCyclesPerMicrotask: 10_000,
+  maxEffectRunsPerFlush: 20_000,
+  windowSize: 5,
+  highUsageRatio: 0.8,
+  maxRootReentrantDepth: 10,
+  enableWindowWarning: true,
+  devMode: false,
+}
+
+let options: Required<CycleProtectionOptions> = {
+  ...defaultOptions,
+} as Required<CycleProtectionOptions>
+
+let effectRunsThisFlush = 0
+let windowUsage: CycleWindowEntry[] = []
+let rootDepth = new WeakMap<object, number>()
+let flushWarned = false
+let rootWarned = false
+let windowWarned = false
+
+export function setCycleProtectionOptions(opts: CycleProtectionOptions): void {
+  options = { ...options, ...opts }
+}
+
+export function resetCycleProtectionStateForTests(): void {
+  options = { ...defaultOptions } as Required<CycleProtectionOptions>
+  effectRunsThisFlush = 0
+  windowUsage = []
+  rootDepth = new WeakMap<object, number>()
+  flushWarned = false
+  rootWarned = false
+  windowWarned = false
+}
+
+export function beginFlushGuard(): void {
+  effectRunsThisFlush = 0
+  flushWarned = false
+  windowWarned = false
+}
+
+export function beforeEffectRunGuard(): boolean {
+  const next = ++effectRunsThisFlush
+  if (next > options.maxFlushCyclesPerMicrotask || next > options.maxEffectRunsPerFlush) {
+    const message = `[fict] cycle protection triggered: flush-budget-exceeded`
+    if (options.devMode) {
+      throw new Error(message)
+    }
+    if (!flushWarned) {
+      flushWarned = true
+      console.warn(message, { effectRuns: next })
+    }
+    return false
+  }
+  return true
+}
+
+export function endFlushGuard(): void {
+  recordWindowUsage(effectRunsThisFlush, options.maxFlushCyclesPerMicrotask)
+  effectRunsThisFlush = 0
+}
+
+export function enterRootGuard(root: object): boolean {
+  const depth = (rootDepth.get(root) ?? 0) + 1
+  if (depth > options.maxRootReentrantDepth) {
+    const message = `[fict] cycle protection triggered: root-reentry`
+    if (options.devMode) {
+      throw new Error(message)
+    }
+    if (!rootWarned) {
+      rootWarned = true
+      console.warn(message, { depth })
+    }
+    return false
+  }
+  rootDepth.set(root, depth)
+  return true
+}
+
+export function exitRootGuard(root: object): void {
+  const depth = rootDepth.get(root)
+  if (depth === undefined) return
+  if (depth <= 1) {
+    rootDepth.delete(root)
+  } else {
+    rootDepth.set(root, depth - 1)
+  }
+}
+
+function recordWindowUsage(used: number, budget: number): void {
+  if (!options.enableWindowWarning) return
+  const entry = { used, budget }
+  windowUsage.push(entry)
+  if (windowUsage.length > options.windowSize) {
+    windowUsage.shift()
+  }
+  if (windowWarned) return
+  if (
+    windowUsage.length >= options.windowSize &&
+    windowUsage.every(item => item.budget > 0 && item.used / item.budget >= options.highUsageRatio)
+  ) {
+    windowWarned = true
+    reportCycle('high-usage-window', {
+      windowSize: options.windowSize,
+      ratio: options.highUsageRatio,
+    })
+  }
+}
+
+function reportCycle(
+  reason: string,
+  detail: Record<string, unknown> | undefined = undefined,
+): void {
+  const hook = getDevtoolsHook()
+  hook?.cycleDetected?.(detail ? { reason, detail } : { reason })
+  console.warn(`[fict] cycle protection triggered: ${reason}`, detail ?? '')
+}

package/src/devtools.ts

@@ -0,0 +1,17 @@
+export interface FictDevtoolsHook {
+  registerSignal: (id: number, value: unknown) => void
+  updateSignal: (id: number, value: unknown) => void
+  registerEffect: (id: number) => void
+  effectRun: (id: number) => void
+  cycleDetected?: (payload: { reason: string; detail?: Record<string, unknown> }) => void
+}
+
+function getGlobalHook(): FictDevtoolsHook | undefined {
+  if (typeof globalThis === 'undefined') return undefined
+  return (globalThis as typeof globalThis & { __FICT_DEVTOOLS_HOOK__?: FictDevtoolsHook })
+    .__FICT_DEVTOOLS_HOOK__
+}
+
+export function getDevtoolsHook(): FictDevtoolsHook | undefined {
+  return getGlobalHook()
+}