@ultrst-armada/frnlts 0.0.0-stage → 0.2.2

package/dist/chunk-FGHXAN4Q.js

@@ -0,0 +1,1125 @@
+import {
+  applyFrnlTheme,
+  getFrnlComponentHandle,
+  getFrnlEvent,
+  getFrnlLibrary,
+  registerFrnlTheme,
+  setFrnlVisualParameter,
+  validateFrnlThemeAgainstDefinition
+} from "./chunk-LG2AFOLX.js";
+
+// src/runtime/core.ts
+import { z } from "zod";
+var lifecyclePhaseSchema = z.enum([
+  "created",
+  "initializing",
+  "mounted",
+  "active",
+  "suspended",
+  "resuming",
+  "disposing",
+  "disposed",
+  "failed"
+]);
+var allowedTransitions = {
+  created: ["initializing", "disposing"],
+  initializing: ["mounted", "failed", "disposing"],
+  mounted: ["active", "suspended", "disposing", "failed"],
+  active: ["suspended", "disposing", "failed"],
+  suspended: ["resuming", "disposing", "failed"],
+  resuming: ["active", "failed", "disposing"],
+  disposing: ["disposed"],
+  disposed: [],
+  failed: ["initializing", "disposing", "disposed"]
+};
+function canTransition(from, to) {
+  return allowedTransitions[from]?.includes(to) ?? false;
+}
+var LifecycleError = class extends Error {
+  constructor(from, to) {
+    super(`Invalid FrnlTS lifecycle transition: ${from} -> ${to}`);
+    this.from = from;
+    this.to = to;
+    this.name = "LifecycleError";
+  }
+  from;
+  to;
+};
+function createLifecycle(initial = "created") {
+  lifecyclePhaseSchema.parse(initial);
+  let phase = initial;
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    get phase() {
+      return phase;
+    },
+    transition(to) {
+      lifecyclePhaseSchema.parse(to);
+      if (to === phase) {
+        return;
+      }
+      if (!canTransition(phase, to)) {
+        throw new LifecycleError(phase, to);
+      }
+      const transitionEvent = { from: phase, to };
+      phase = to;
+      for (const listener of [...listeners]) {
+        listener(transitionEvent);
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+var contractSchema = z.object({
+  id: z.string().min(1),
+  version: z.number().int().positive(),
+  inputs: z.record(z.string(), z.unknown()).optional(),
+  outputs: z.record(z.string(), z.unknown()).optional(),
+  events: z.array(z.string().min(1)).optional(),
+  commands: z.array(z.string().min(1)).optional(),
+  capabilities: z.array(z.string().min(1)).optional()
+});
+function defineContract(contract) {
+  contractSchema.parse(contract);
+  return Object.freeze({ ...contract });
+}
+var capabilitySchema = z.object({
+  id: z.string().min(1),
+  version: z.number().int().positive(),
+  provides: z.array(z.string().min(1)).optional(),
+  requires: z.array(z.string().min(1)).optional()
+});
+function defineCapability(capability) {
+  capabilitySchema.parse(capability);
+  return Object.freeze({ ...capability });
+}
+var FrnlFault = class extends Error {
+  code;
+  recoverable;
+  retryable;
+  cause;
+  constructor(options) {
+    super(options.message);
+    this.name = "FrnlFault";
+    this.code = options.code;
+    this.recoverable = options.recoverable ?? false;
+    this.retryable = options.retryable ?? false;
+    this.cause = options.cause;
+  }
+};
+function defineEffect(id, run) {
+  z.string().min(1).parse(id);
+  if (typeof run !== "function") {
+    throw new TypeError("Effect run must be a function");
+  }
+  return Object.freeze({ id, run });
+}
+function defineCommand(id, payload) {
+  z.string().min(1).parse(id);
+  return Object.freeze({ id, payload });
+}
+
+// src/runtime/resources.ts
+function defineResource(resource) {
+  if (!resource || !resource.id || typeof resource.id !== "string") {
+    throw new TypeError("Invalid Frnl resource: missing valid id");
+  }
+  if (typeof resource.acquire !== "function") {
+    throw new TypeError(`Invalid Frnl resource '${resource.id}': acquire must be a function`);
+  }
+  return Object.freeze({ ...resource });
+}
+function createResourceController(resource, scopeId) {
+  const controller = new AbortController();
+  const state = {
+    status: "idle",
+    value: void 0,
+    error: void 0,
+    inFlightPromise: void 0,
+    inFlightReleasePromise: void 0
+  };
+  const context = Object.freeze({
+    signal: controller.signal,
+    scopeId
+  });
+  return {
+    id: resource.id,
+    get status() {
+      return state.status;
+    },
+    get value() {
+      return state.value;
+    },
+    get error() {
+      return state.error;
+    },
+    async load() {
+      if (state.status === "ready") {
+        return state.value;
+      }
+      if (state.status === "loading" && state.inFlightPromise) {
+        return state.inFlightPromise;
+      }
+      if (state.status === "released") {
+        throw new FrnlFault({
+          code: "RESOURCE_RELEASED",
+          message: `Resource '${resource.id}' has already been released`
+        });
+      }
+      if (controller.signal.aborted) {
+        throw new FrnlFault({
+          code: "RESOURCE_ABORTED",
+          message: `Resource '${resource.id}' acquisition aborted`
+        });
+      }
+      state.status = "loading";
+      state.error = void 0;
+      state.inFlightPromise = (async () => {
+        try {
+          const acquired = await Promise.resolve(resource.acquire(context));
+          if (controller.signal.aborted || state.status === "released") {
+            if (resource.release && acquired !== void 0) {
+              try {
+                await Promise.resolve(resource.release(acquired, context));
+              } catch {
+              }
+            }
+            throw new FrnlFault({
+              code: "RESOURCE_ABORTED",
+              message: `Resource '${resource.id}' acquired after abort or release`
+            });
+          }
+          state.value = acquired;
+          state.status = "ready";
+          return acquired;
+        } catch (err) {
+          if (state.status !== "released") {
+            state.status = "error";
+            state.error = err instanceof FrnlFault ? err : new FrnlFault({
+              code: "RESOURCE_ACQUIRE_FAILED",
+              message: err instanceof Error ? err.message : String(err),
+              retryable: true,
+              cause: err
+            });
+          }
+          throw state.error ?? err;
+        } finally {
+          state.inFlightPromise = void 0;
+        }
+      })();
+      return state.inFlightPromise;
+    },
+    async release() {
+      if (state.status === "released") {
+        return;
+      }
+      if (state.inFlightReleasePromise) {
+        return state.inFlightReleasePromise;
+      }
+      state.inFlightReleasePromise = (async () => {
+        state.status = "released";
+        controller.abort();
+        if (state.inFlightPromise) {
+          try {
+            await state.inFlightPromise;
+          } catch {
+          }
+        }
+        const previousValue = state.value;
+        state.value = void 0;
+        if (previousValue !== void 0 && resource.release) {
+          try {
+            await Promise.resolve(resource.release(previousValue, context));
+          } catch (releaseErr) {
+            state.error = releaseErr instanceof FrnlFault ? releaseErr : new FrnlFault({
+              code: "RESOURCE_RELEASE_FAILED",
+              message: releaseErr instanceof Error ? releaseErr.message : String(releaseErr),
+              cause: releaseErr
+            });
+            throw state.error;
+          }
+        }
+      })();
+      return state.inFlightReleasePromise;
+    }
+  };
+}
+function createScope(id, parent) {
+  if (parent && (parent.signal.aborted || parent.isDisposed)) {
+    throw new FrnlFault({
+      code: "SCOPE_DISPOSED",
+      message: `Cannot create child scope from disposed parent '${parent.id}'`
+    });
+  }
+  const controller = new AbortController();
+  const resources = /* @__PURE__ */ new Set();
+  const childScopes = /* @__PURE__ */ new Set();
+  let isDisposed = false;
+  let inFlightDisposePromise;
+  const scope = {
+    id,
+    parent,
+    signal: controller.signal,
+    get isDisposed() {
+      return isDisposed;
+    },
+    _registerChild(child) {
+      if (isDisposed) {
+        void child.dispose();
+      } else {
+        childScopes.add(child);
+      }
+    },
+    _removeChild(child) {
+      childScopes.delete(child);
+    },
+    add(resource) {
+      if (controller.signal.aborted || isDisposed) {
+        throw new FrnlFault({
+          code: "SCOPE_DISPOSED",
+          message: `Scope '${id}' has been disposed`
+        });
+      }
+      const resCtrl = createResourceController(resource, id);
+      resources.add(resCtrl);
+      return resCtrl;
+    },
+    createChildScope(childId) {
+      if (controller.signal.aborted || isDisposed) {
+        throw new FrnlFault({
+          code: "SCOPE_DISPOSED",
+          message: `Cannot create child scope from disposed parent '${id}'`
+        });
+      }
+      return createScope(childId, scope);
+    },
+    async dispose() {
+      if (isDisposed) {
+        return;
+      }
+      if (inFlightDisposePromise) {
+        return inFlightDisposePromise;
+      }
+      inFlightDisposePromise = (async () => {
+        isDisposed = true;
+        if (!controller.signal.aborted) {
+          controller.abort();
+        }
+        if (parent?._removeChild) {
+          parent._removeChild(scope);
+        }
+        const childPromises = [...childScopes].map((child) => child.dispose());
+        const resourcePromises = [...resources].map((res) => res.release());
+        childScopes.clear();
+        resources.clear();
+        await Promise.allSettled([...childPromises, ...resourcePromises]);
+      })();
+      return inFlightDisposePromise;
+    }
+  };
+  if (parent?._registerChild) {
+    parent._registerChild(scope);
+  }
+  if (parent) {
+    parent.signal.addEventListener("abort", () => void scope.dispose(), { once: true });
+  }
+  return scope;
+}
+
+// src/runtime/dependencies.ts
+var DependencyGraph = class _DependencyGraph {
+  nodes = /* @__PURE__ */ new Map();
+  providers = /* @__PURE__ */ new Map();
+  // capability -> set of nodeIds
+  register(node) {
+    if (!node || !node.id || typeof node.id !== "string") {
+      throw new TypeError("Invalid dependency node: id must be a non-empty string");
+    }
+    if (this.nodes.has(node.id)) {
+      throw new Error(`Duplicate dependency node: ${node.id}`);
+    }
+    const frozen = Object.freeze({ ...node });
+    this.nodes.set(node.id, frozen);
+    for (const prov of node.provides ?? []) {
+      if (!this.providers.has(prov)) {
+        this.providers.set(prov, /* @__PURE__ */ new Set());
+      }
+      this.providers.get(prov).add(node.id);
+    }
+  }
+  registerCapability(capability) {
+    this.register({
+      id: capability.id,
+      version: capability.version,
+      requires: capability.requires,
+      provides: capability.provides
+    });
+  }
+  get(id) {
+    return this.nodes.get(id);
+  }
+  list() {
+    return [...this.nodes.values()];
+  }
+  resolveDependencyNodeId(dependencyName) {
+    if (this.nodes.has(dependencyName)) {
+      return dependencyName;
+    }
+    const provSet = this.providers.get(dependencyName);
+    if (provSet && provSet.size > 0) {
+      return [...provSet][0];
+    }
+    return void 0;
+  }
+  validate() {
+    const errors = [];
+    for (const node of this.nodes.values()) {
+      for (const req of node.requires ?? []) {
+        const resolvedId = this.resolveDependencyNodeId(req);
+        if (!resolvedId) {
+          errors.push(`${node.id} requires missing dependency ${req}`);
+        }
+      }
+    }
+    return errors;
+  }
+  topologicalOrder() {
+    const visiting = /* @__PURE__ */ new Set();
+    const visited = /* @__PURE__ */ new Set();
+    const result = [];
+    const visit = (id, path = []) => {
+      if (visiting.has(id)) {
+        const cycle = [...path, id].join(" -> ");
+        throw new Error(`Dependency cycle detected at ${id}: ${cycle}`);
+      }
+      if (visited.has(id)) {
+        return;
+      }
+      visiting.add(id);
+      const node = this.nodes.get(id);
+      for (const req of node?.requires ?? []) {
+        const resolvedId = this.resolveDependencyNodeId(req);
+        if (resolvedId && this.nodes.has(resolvedId)) {
+          visit(resolvedId, [...path, id]);
+        }
+      }
+      visiting.delete(id);
+      visited.add(id);
+      result.push(id);
+    };
+    for (const id of this.nodes.keys()) {
+      visit(id);
+    }
+    return result;
+  }
+  clear() {
+    this.nodes.clear();
+    this.providers.clear();
+  }
+  static fromCapabilities(capabilities) {
+    const graph = new _DependencyGraph();
+    for (const cap of capabilities) {
+      graph.registerCapability(cap);
+    }
+    return graph;
+  }
+};
+
+// src/runtime/registry.ts
+var FrnlRegistry = class {
+  entries = /* @__PURE__ */ new Map();
+  register(entry) {
+    if (!entry || !entry.id || typeof entry.id !== "string") {
+      throw new TypeError("Invalid registry entry: id must be a non-empty string");
+    }
+    if (!Number.isInteger(entry.version) || entry.version < 1) {
+      throw new TypeError(
+        `Invalid registry entry '${entry.id}': version must be a positive integer, received ${entry.version}`
+      );
+    }
+    const current = this.entries.get(entry.id);
+    if (current && current.version > entry.version) {
+      throw new Error(
+        `Cannot register older version (${entry.version}) of '${entry.id}'. Active version is ${current.version}.`
+      );
+    }
+    this.entries.set(entry.id, Object.freeze({ ...entry }));
+  }
+  has(id) {
+    return this.entries.has(id);
+  }
+  get(id) {
+    return this.entries.get(id);
+  }
+  resolve(id) {
+    const entry = this.entries.get(id);
+    if (!entry) {
+      throw new Error(`Frnl registration not found: ${id}`);
+    }
+    return entry.value;
+  }
+  list() {
+    return [...this.entries.values()];
+  }
+  requireCapabilities(id, available) {
+    const entry = this.entries.get(id);
+    if (!entry) {
+      throw new Error(`Frnl registration not found: ${id}`);
+    }
+    const availableSet = new Set(available);
+    const required = [];
+    if (entry.contract?.capabilities) {
+      required.push(...entry.contract.capabilities);
+    }
+    if (entry.capabilities) {
+      for (const cap of entry.capabilities) {
+        if (cap.requires) {
+          required.push(...cap.requires);
+        }
+      }
+    }
+    for (const cap of required) {
+      if (!availableSet.has(cap)) {
+        throw new Error(`Missing capability '${cap}' for registration '${id}'`);
+      }
+    }
+  }
+  toDependencyGraph() {
+    const graph = new DependencyGraph();
+    for (const entry of this.entries.values()) {
+      const requires = [];
+      if (entry.contract?.capabilities) {
+        requires.push(...entry.contract.capabilities);
+      }
+      const provides = [];
+      if (entry.capabilities) {
+        for (const cap of entry.capabilities) {
+          if (cap.provides) {
+            provides.push(...cap.provides);
+          }
+        }
+      }
+      graph.register({
+        id: entry.id,
+        version: entry.version,
+        requires,
+        provides
+      });
+    }
+    return graph;
+  }
+  clear() {
+    this.entries.clear();
+  }
+};
+
+// src/runtime/routing.ts
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizePattern(pattern) {
+  if (!pattern || pattern.trim() === "") {
+    return "/";
+  }
+  const trimmed = pattern.trim();
+  const withLeading = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withLeading.length > 1 && withLeading.endsWith("/") ? withLeading.slice(0, -1) : withLeading;
+}
+function compileRoute(pattern) {
+  const norm = normalizePattern(pattern);
+  const paramNames = [];
+  let wildcardName;
+  const parts = norm.split("/");
+  const regexParts = parts.map((part) => {
+    if (part.startsWith(":")) {
+      const name = part.slice(1);
+      paramNames.push(name);
+      return "([^/]+)";
+    }
+    if (part === "*" || part.startsWith("*")) {
+      const name = part.length > 1 ? part.slice(1) : "wildcard";
+      wildcardName = name;
+      paramNames.push(name);
+      return "(.*)";
+    }
+    return escapeRegex(part);
+  });
+  const source = regexParts.join("/");
+  return {
+    regex: new RegExp(`^${source}/?$`),
+    paramNames,
+    wildcardName
+  };
+}
+function matchRoute(route, url) {
+  const parsed = new URL(url, "http://frnl.local");
+  const compiled = compileRoute(route.pattern);
+  const match = compiled.regex.exec(parsed.pathname);
+  if (!match) {
+    return null;
+  }
+  const params = {};
+  compiled.paramNames.forEach((name, index) => {
+    const rawVal = match[index + 1] ?? "";
+    params[name] = decodeURIComponent(rawVal);
+  });
+  const query = {};
+  parsed.searchParams.forEach((value, key) => {
+    query[key] = value;
+  });
+  return {
+    id: route.id,
+    params: Object.freeze(params),
+    query: Object.freeze(query),
+    path: parsed.pathname
+  };
+}
+function buildRouteUrl(route, params = {}, query = {}, options = {}) {
+  const norm = normalizePattern(route.pattern);
+  const parts = norm.split("/");
+  const consumedParams = /* @__PURE__ */ new Set();
+  const builtParts = parts.map((part) => {
+    if (part.startsWith(":")) {
+      const name = part.slice(1);
+      consumedParams.add(name);
+      const value = params[name];
+      if (value === void 0 || value === null || value === "") {
+        throw new Error(`Missing route parameter: ${name}`);
+      }
+      return encodeURIComponent(value);
+    }
+    if (part === "*" || part.startsWith("*")) {
+      const name = part.length > 1 ? part.slice(1) : "wildcard";
+      consumedParams.add(name);
+      consumedParams.add("wildcard");
+      const value = params[name] ?? params.wildcard ?? "";
+      return value.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+    }
+    return part;
+  });
+  const path = builtParts.join("/") || "/";
+  const unconsumed = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (!consumedParams.has(key)) {
+      if (options.strict) {
+        throw new Error(`Unknown route parameter: ${key}`);
+      }
+      unconsumed[key] = value;
+    }
+  }
+  const finalQuery = {
+    ...options.appendUnmatchedParamsToQuery ? unconsumed : {},
+    ...query
+  };
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(finalQuery)) {
+    if (value !== void 0 && value !== null) {
+      searchParams.set(key, value);
+    }
+  }
+  const queryString = searchParams.toString();
+  return queryString ? `${path}?${queryString}` : path;
+}
+var FrnlRouter = class {
+  routeMap = /* @__PURE__ */ new Map();
+  patternMap = /* @__PURE__ */ new Map();
+  // pattern -> routeId
+  constructor(routes = []) {
+    for (const route of routes) {
+      this.addRoute(route);
+    }
+  }
+  addRoute(route) {
+    if (!route || !route.id || typeof route.id !== "string") {
+      throw new TypeError("Invalid route: id must be a non-empty string");
+    }
+    if (this.routeMap.has(route.id)) {
+      throw new Error(`Duplicate route id: ${route.id}`);
+    }
+    const norm = normalizePattern(route.pattern);
+    const existingRouteId = this.patternMap.get(norm);
+    if (existingRouteId) {
+      throw new Error(
+        `Conflicting route pattern '${route.pattern}' already registered by route '${existingRouteId}'`
+      );
+    }
+    this.routeMap.set(route.id, Object.freeze({ ...route }));
+    this.patternMap.set(norm, route.id);
+  }
+  getRoute(id) {
+    return this.routeMap.get(id);
+  }
+  match(url) {
+    for (const route of this.routeMap.values()) {
+      const match = matchRoute(route, url);
+      if (match) {
+        return match;
+      }
+    }
+    return null;
+  }
+  async resolve(url) {
+    const match = this.match(url);
+    if (!match) {
+      return null;
+    }
+    const route = this.routeMap.get(match.id);
+    const data = route?.load ? await route.load() : void 0;
+    return { match, data };
+  }
+  list() {
+    return [...this.routeMap.values()];
+  }
+  clear() {
+    this.routeMap.clear();
+    this.patternMap.clear();
+  }
+};
+
+// src/runtime/accessibility.ts
+function validateAccessibility(contract, attributes) {
+  const issues = [];
+  if (contract.nameRequired) {
+    const hasLabel = typeof attributes["aria-label"] === "string" && attributes["aria-label"].trim().length > 0;
+    const hasLabelledBy = typeof attributes["aria-labelledby"] === "string" && attributes["aria-labelledby"].trim().length > 0;
+    if (!hasLabel && !hasLabelledBy) {
+      issues.push({
+        code: "ACCESSIBLE_NAME_REQUIRED",
+        message: "An accessible name is required via aria-label or aria-labelledby."
+      });
+    }
+  }
+  for (const attr of contract.requiredAttributes ?? []) {
+    if (!(attr in attributes) || attributes[attr] === void 0 || attributes[attr] === null || attributes[attr] === "") {
+      issues.push({
+        code: "REQUIRED_ATTRIBUTE_MISSING",
+        message: `Missing required attribute: ${attr}`
+      });
+    }
+  }
+  if (contract.role && attributes.role !== contract.role) {
+    issues.push({
+      code: "ROLE_MISMATCH",
+      message: `Expected role '${contract.role}', received '${String(attributes.role)}'`
+    });
+  }
+  if (contract.focusable) {
+    if (attributes.tabIndex === -1 || attributes["aria-hidden"] === true) {
+      issues.push({
+        code: "FOCUS_RESTRICTED",
+        message: "Element is marked as focusable but focus is suppressed via tabIndex or aria-hidden."
+      });
+    }
+  }
+  return issues;
+}
+
+// src/runtime/store.ts
+import { createStore } from "zustand/vanilla";
+import { z as z3 } from "zod";
+
+// src/runtime/validation.ts
+import { z as z2 } from "zod";
+var entityIdSchema = z2.string().min(1);
+var stateNameSchema = z2.string().min(1);
+var propertyKeySchema = z2.string().min(1);
+var propertyValueSchema = z2.unknown();
+var propertiesSchema = z2.record(z2.string(), propertyValueSchema);
+var frnlThemeStateSchema = z2.object({
+  visualParameters: propertiesSchema.optional()
+}).strict();
+var frnlThemeComponentSchema = z2.object({
+  states: z2.record(z2.string().min(1), frnlThemeStateSchema).optional()
+}).strict();
+var frnlThemeDefinitionSchema = z2.record(
+  z2.string().min(1),
+  frnlThemeComponentSchema
+);
+var entityStateSchema = z2.object({
+  state: stateNameSchema,
+  properties: propertiesSchema
+});
+var entityStateChangedPayloadSchema = z2.object({
+  entityId: entityIdSchema,
+  previousState: stateNameSchema,
+  state: stateNameSchema
+});
+var entityPropertyChangedPayloadSchema = z2.object({
+  entityId: entityIdSchema,
+  key: propertyKeySchema,
+  value: propertyValueSchema
+});
+var flowTriggeredPayloadSchema = z2.object({
+  flowId: z2.string().min(1),
+  componentId: entityIdSchema,
+  trigger: z2.string().min(1),
+  payload: propertyValueSchema.optional()
+});
+var frnlEventSchema = z2.discriminatedUnion("type", [
+  z2.object({ type: z2.literal("entity.stateChanged"), payload: entityStateChangedPayloadSchema }),
+  z2.object({ type: z2.literal("entity.propertyChanged"), payload: entityPropertyChangedPayloadSchema }),
+  z2.object({ type: z2.literal("flow.triggered"), payload: flowTriggeredPayloadSchema })
+]);
+function parseFrnlInput(schema, input) {
+  return schema.parse(input);
+}
+function validateFrnlInput(schema, input) {
+  return schema.safeParse(input).success;
+}
+
+// src/runtime/store.ts
+function createFrnlStore(initial) {
+  const initialEntities = z3.record(z3.string(), entityStateSchema).parse(initial?.entities ?? {});
+  return createStore((set, get) => ({
+    entities: initialEntities,
+    events: [],
+    componentDefinitions: {},
+    eventHandlers: {},
+    componentParents: {},
+    visualOverrides: {},
+    themes: {},
+    componentThemes: {},
+    libraries: {},
+    registerComponentDefinition: (componentId, definition) => {
+      const id = entityIdSchema.parse(componentId);
+      for (const theme of Object.values(get().themes)) {
+        validateFrnlThemeAgainstDefinition(theme, definition);
+      }
+      set((current) => ({ componentDefinitions: { ...current.componentDefinitions, [id]: definition } }));
+    },
+    registerTheme: (name, theme) => {
+      const themeName = z3.string().min(1).parse(name);
+      const validatedTheme = frnlThemeDefinitionSchema.parse(theme);
+      for (const definition of Object.values(get().componentDefinitions)) {
+        validateFrnlThemeAgainstDefinition(validatedTheme, definition);
+      }
+      set((current) => ({
+        themes: { ...current.themes, [themeName]: validatedTheme }
+      }));
+    },
+    applyTheme: (componentId, themeName) => {
+      const id = entityIdSchema.parse(componentId);
+      const name = z3.string().min(1).parse(themeName);
+      set((current) => {
+        if (!current.entities[id]) {
+          throw new Error(`Unknown Frnl component: ${id}`);
+        }
+        if (!current.themes[name]) {
+          throw new Error(`Unknown Frnl theme: ${name}`);
+        }
+        const visualOverrides = { ...current.visualOverrides };
+        delete visualOverrides[id];
+        return {
+          componentThemes: { ...current.componentThemes, [id]: name },
+          visualOverrides
+        };
+      });
+    },
+    registerEventHandlers: (componentId, handlers) => {
+      const id = entityIdSchema.parse(componentId);
+      set((current) => ({ eventHandlers: { ...current.eventHandlers, [id]: handlers } }));
+    },
+    unregisterEventHandlers: (componentId) => {
+      const id = entityIdSchema.parse(componentId);
+      set((current) => {
+        const next = { ...current.eventHandlers };
+        delete next[id];
+        return { eventHandlers: next };
+      });
+    },
+    unregisterEntity: (entityId) => {
+      const id = entityIdSchema.parse(entityId);
+      set((current) => {
+        const entities = { ...current.entities };
+        const componentDefinitions = { ...current.componentDefinitions };
+        const eventHandlers = { ...current.eventHandlers };
+        const componentParents = { ...current.componentParents };
+        const visualOverrides = { ...current.visualOverrides };
+        const componentThemes = { ...current.componentThemes };
+        delete entities[id];
+        delete componentDefinitions[id];
+        delete eventHandlers[id];
+        delete componentParents[id];
+        delete visualOverrides[id];
+        delete componentThemes[id];
+        return { entities, componentDefinitions, eventHandlers, componentParents, visualOverrides, componentThemes };
+      });
+    },
+    setVisualOverride: (componentId, parameter, value) => {
+      const id = entityIdSchema.parse(componentId);
+      const key = propertyKeySchema.parse(parameter);
+      set((current) => ({
+        visualOverrides: {
+          ...current.visualOverrides,
+          [id]: { ...current.visualOverrides[id] ?? {}, [key]: value }
+        }
+      }));
+    },
+    clearVisualOverrides: (componentId) => {
+      const id = entityIdSchema.parse(componentId);
+      set((current) => {
+        const visualOverrides = { ...current.visualOverrides };
+        delete visualOverrides[id];
+        return { visualOverrides };
+      });
+    },
+    registerLibrary: (address, library) => {
+      const key = z3.string().min(1).parse(address);
+      set((current) => ({ libraries: { ...current.libraries, [key]: library } }));
+    },
+    unregisterLibrary: (address) => {
+      const key = z3.string().min(1).parse(address);
+      set((current) => {
+        const libraries = { ...current.libraries };
+        delete libraries[key];
+        return { libraries };
+      });
+    },
+    registerComponentParent: (componentId, parentId) => {
+      const id = entityIdSchema.parse(componentId);
+      const parent = parentId === void 0 ? void 0 : entityIdSchema.parse(parentId);
+      if (parent === id) throw new Error(`Frnl component cannot be its own parent: ${id}`);
+      set((current) => ({
+        componentParents: { ...current.componentParents, [id]: parent }
+      }));
+    },
+    emit: (event) => {
+      const validated = frnlEventSchema.parse(event);
+      set((current) => ({ events: [...current.events, validated] }));
+    },
+    /**
+     * registerEntity performs an idempotent upsert of declarative metadata.
+     *
+     * Semantic Authority Model:
+     * - Declarative Metadata (authoritative from registration / props):
+     *   `properties`.
+     * - Runtime State (authoritative from runtime / interactions):
+     *   `state` (active state is preserved across re-registrations),
+     *   `events` (event history is preserved).
+     */
+    registerEntity: (entityId, entity) => {
+      const id = entityIdSchema.parse(entityId);
+      const validated = entityStateSchema.parse(entity);
+      set((current) => {
+        const existing = current.entities[id];
+        const nextEntity = existing ? {
+          // Runtime state is preserved if already set
+          state: existing.state,
+          // Declarative metadata is merged / updated
+          properties: { ...existing.properties, ...validated.properties }
+        } : validated;
+        return {
+          entities: { ...current.entities, [id]: nextEntity }
+        };
+      });
+    },
+    setEntityState: (entityId, state) => {
+      const id = entityIdSchema.parse(entityId);
+      const nextState = stateNameSchema.parse(state);
+      set((current) => {
+        const entity = current.entities[id];
+        if (!entity) return current;
+        if (entity.state === nextState) return current;
+        const previousState = entity.state;
+        const entityPayload = entityStateChangedPayloadSchema.parse({
+          entityId: id,
+          previousState,
+          state: nextState
+        });
+        const newEvents = [
+          { type: "entity.stateChanged", payload: entityPayload }
+        ];
+        const visualOverrides = { ...current.visualOverrides };
+        delete visualOverrides[id];
+        return {
+          entities: { ...current.entities, [id]: { ...entity, state: nextState } },
+          visualOverrides,
+          events: [...current.events, ...newEvents]
+        };
+      });
+    },
+    setEntityProperty: (entityId, key, value) => {
+      const id = entityIdSchema.parse(entityId);
+      const property = propertyKeySchema.parse(key);
+      set((current) => {
+        const entity = current.entities[id];
+        if (!entity) return current;
+        const payload = entityPropertyChangedPayloadSchema.parse({
+          entityId: id,
+          key: property,
+          value
+        });
+        return {
+          entities: {
+            ...current.entities,
+            [id]: { ...entity, properties: { ...entity.properties, [property]: value } }
+          },
+          events: [...current.events, { type: "entity.propertyChanged", payload }]
+        };
+      });
+    },
+    setEntityProperties: (entityId, properties) => {
+      const id = entityIdSchema.parse(entityId);
+      const validated = propertiesSchema.parse(properties);
+      set((current) => {
+        const entity = current.entities[id];
+        if (!entity) return current;
+        const newEvents = [];
+        for (const [key, value] of Object.entries(validated)) {
+          if (entity.properties[key] !== value) {
+            newEvents.push({
+              type: "entity.propertyChanged",
+              payload: entityPropertyChangedPayloadSchema.parse({
+                entityId: id,
+                key,
+                value
+              })
+            });
+          }
+        }
+        return {
+          entities: {
+            ...current.entities,
+            [id]: {
+              ...entity,
+              properties: { ...entity.properties, ...validated }
+            }
+          },
+          events: [...current.events, ...newEvents]
+        };
+      });
+    },
+    triggerFlow: (flowId, componentId, trigger, payload) => {
+      const fId = z3.string().min(1).parse(flowId);
+      const cId = entityIdSchema.parse(componentId);
+      const trig = z3.string().min(1).parse(trigger);
+      const eventPayload = flowTriggeredPayloadSchema.parse({
+        flowId: fId,
+        componentId: cId,
+        trigger: trig,
+        payload
+      });
+      set((current) => ({
+        events: [
+          ...current.events,
+          { type: "flow.triggered", payload: eventPayload }
+        ]
+      }));
+    }
+  }));
+}
+
+// src/runtime/facade.ts
+var FrnlFacade = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  component(componentId) {
+    return getFrnlComponentHandle(this.store, componentId);
+  }
+  event(componentId, eventName) {
+    return getFrnlEvent(this.store, componentId, eventName);
+  }
+  library(address) {
+    return getFrnlLibrary(this.store, address);
+  }
+  setVisualParameter(address, value) {
+    setFrnlVisualParameter(this.store, address, value);
+  }
+  registerTheme(name, theme) {
+    registerFrnlTheme(this.store, name, theme);
+  }
+  applyThemeToAllComponents(themeName) {
+    if (!this.store.getState().themes[themeName]) {
+      throw new Error(`Unknown Frnl theme: ${themeName}`);
+    }
+    for (const componentId of Object.keys(this.store.getState().entities)) {
+      applyFrnlTheme(this.store, componentId, themeName);
+    }
+  }
+};
+function createFrnlFacade(store) {
+  return new FrnlFacade(store);
+}
+
+// src/runtime/component-definition.ts
+import { z as z4 } from "zod";
+var frnlVisualDefinitionSchema = z4.object({
+  parameters: z4.record(z4.string(), z4.unknown())
+});
+var frnlPhaseDefinitionSchema = z4.object({
+  visualDefinition: frnlVisualDefinitionSchema
+});
+var frnlEventDefinitionSchema = z4.object({
+  functionId: z4.string().min(1)
+});
+var frnlStateDefinitionSchema = z4.object({
+  name: z4.string().min(1),
+  events: z4.record(z4.string().min(1), frnlEventDefinitionSchema),
+  visualParameters: z4.record(z4.string(), z4.unknown()).default({}),
+  phases: z4.object({
+    attackPhase: frnlPhaseDefinitionSchema.optional(),
+    sustainPhase: frnlPhaseDefinitionSchema,
+    releasePhase: frnlPhaseDefinitionSchema.optional()
+  })
+});
+var frnlComponentDefinitionSchema = z4.object({
+  name: z4.string().min(1),
+  states: z4.record(z4.string().min(1), frnlStateDefinitionSchema)
+});
+function defineFrnlComponent(definition) {
+  return frnlComponentDefinitionSchema.parse(definition);
+}
+
+export {
+  lifecyclePhaseSchema,
+  canTransition,
+  LifecycleError,
+  createLifecycle,
+  contractSchema,
+  defineContract,
+  capabilitySchema,
+  defineCapability,
+  FrnlFault,
+  defineEffect,
+  defineCommand,
+  defineResource,
+  createResourceController,
+  createScope,
+  DependencyGraph,
+  FrnlRegistry,
+  matchRoute,
+  buildRouteUrl,
+  FrnlRouter,
+  validateAccessibility,
+  entityIdSchema,
+  stateNameSchema,
+  propertyKeySchema,
+  propertyValueSchema,
+  propertiesSchema,
+  frnlThemeStateSchema,
+  frnlThemeComponentSchema,
+  frnlThemeDefinitionSchema,
+  entityStateSchema,
+  entityStateChangedPayloadSchema,
+  entityPropertyChangedPayloadSchema,
+  flowTriggeredPayloadSchema,
+  frnlEventSchema,
+  parseFrnlInput,
+  validateFrnlInput,
+  createFrnlStore,
+  FrnlFacade,
+  createFrnlFacade,
+  frnlVisualDefinitionSchema,
+  frnlPhaseDefinitionSchema,
+  frnlEventDefinitionSchema,
+  frnlStateDefinitionSchema,
+  frnlComponentDefinitionSchema,
+  defineFrnlComponent
+};