silvery 0.19.2 → 0.21.1

package/dist/layout-engine-Ca_nbtfL.mjs

@@ -0,0 +1,67 @@
+//#region packages/ag-term/src/layout-engine.ts
+let layoutEngine = null;
+/**
+* Set the global layout engine instance.
+* Must be called before rendering.
+*/
+function setLayoutEngine(engine) {
+	layoutEngine = engine;
+}
+/**
+* Get the global layout engine instance.
+* Throws if not initialized.
+*/
+function getLayoutEngine() {
+	if (!layoutEngine) throw new Error("Layout engine not initialized. Call setLayoutEngine() or initYoga()/initFlexily() first.");
+	return layoutEngine;
+}
+/**
+* Check if a layout engine is initialized.
+*/
+function isLayoutEngineInitialized() {
+	return layoutEngine !== null;
+}
+/**
+* Get the layout constants from the current engine.
+* Convenience function for accessing constants.
+*/
+function getConstants() {
+	return getLayoutEngine().constants;
+}
+/**
+* Runtime guard: throws if the active layout engine doesn't advertise the named capability.
+*
+* Used by Phase A0.1+ primitives (`<Box fitWidth>`, `<Box containerQueries>`, cq* units,
+* style math functions) at their first-paint resolution path. Under `yoga` (or pre-A0.1
+* flexily), the throw happens at first paint with a one-line fix instruction in the error
+* message. No silent fallback — silent fallback under yoga would look like a fresh render
+* bug and cost hours of debugging.
+*
+* @param name     The capability key being checked (e.g. `"fitWidth"`, `"containerQueries"`).
+* @param consumer A human-readable label for the call site, e.g. `"<Box fitWidth>"` or
+*                 `"cqi unit in 'padding'"`. Surfaces in the error message.
+*/
+function requireCapability(name, consumer) {
+	const engine = getLayoutEngine();
+	if (!engine.capabilities[name]) throw new Error(`${consumer} requires layout engine capability "${name}" — current engine "${engine.name}" doesn't support it. Switch to flexily: set SILVERY_ENGINE=flexily, OR call ensureDefaultLayoutEngine("flexily") before render.`);
+}
+/**
+* Initialize the layout engine if not already set.
+*
+* @param engineType - 'flexily', 'flexily-classic', or 'yoga'. If not provided, checks
+*                     SILVERY_ENGINE env var, then defaults to 'flexily'.
+*/
+async function ensureDefaultLayoutEngine(engineType) {
+	if (isLayoutEngineInitialized()) return;
+	if ((engineType ?? process.env.SILVERY_ENGINE?.toLowerCase() ?? "flexily") === "yoga") {
+		const { initYogaEngine } = await import("./yoga-adapter-1ex8r0ws.mjs");
+		setLayoutEngine(await initYogaEngine());
+	} else {
+		const { createFlexilyZeroEngine } = await import("./flexily-zero-adapter-D6hcFgrH.mjs");
+		setLayoutEngine(createFlexilyZeroEngine());
+	}
+}
+//#endregion
+export { requireCapability as a, isLayoutEngineInitialized as i, getConstants as n, setLayoutEngine as o, getLayoutEngine as r, ensureDefaultLayoutEngine as t };
+
+//# sourceMappingURL=layout-engine-Ca_nbtfL.mjs.map

package/dist/layout-engine-Ca_nbtfL.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-engine-Ca_nbtfL.mjs","names":[],"sources":["../packages/ag-term/src/layout-engine.ts"],"sourcesContent":["/**\n * Layout Engine Abstraction\n *\n * Provides a pluggable interface for layout engines (Yoga, Flexily, etc.)\n * This allows silvery to use different layout backends without code changes.\n *\n * Core type interfaces (LayoutNode, MeasureFunc, MeasureMode) live in\n * @silvery/ag/layout-types. This file contains the runtime engine management.\n */\n\nimport type { LayoutNode } from \"@silvery/ag/layout-types\"\n\n// ============================================================================\n// Branded Types for Type Safety\n// ============================================================================\n\n/**\n * Branded types prevent accidentally mixing up layout constant categories.\n * E.g., you can't pass an AlignValue where a FlexDirectionValue is expected.\n */\nexport type FlexDirectionValue = number & { readonly __brand: \"FlexDirection\" }\nexport type WrapValue = number & { readonly __brand: \"Wrap\" }\nexport type AlignValue = number & { readonly __brand: \"Align\" }\nexport type JustifyValue = number & { readonly __brand: \"Justify\" }\nexport type EdgeValue = number & { readonly __brand: \"Edge\" }\nexport type GutterValue = number & { readonly __brand: \"Gutter\" }\nexport type DisplayValue = number & { readonly __brand: \"Display\" }\nexport type PositionTypeValue = number & { readonly __brand: \"PositionType\" }\nexport type OverflowValue = number & { readonly __brand: \"Overflow\" }\nexport type DirectionValue = number & { readonly __brand: \"Direction\" }\nexport type MeasureModeValue = number & { readonly __brand: \"MeasureMode\" }\n\n// ============================================================================\n// Layout Constants Interface\n// ============================================================================\n\n/**\n * Constants for layout configuration.\n * These are the same across Yoga and Flexily.\n * Uses branded types for compile-time safety.\n */\nexport interface LayoutConstants {\n  // Flex Direction\n  FLEX_DIRECTION_COLUMN: FlexDirectionValue\n  FLEX_DIRECTION_COLUMN_REVERSE: FlexDirectionValue\n  FLEX_DIRECTION_ROW: FlexDirectionValue\n  FLEX_DIRECTION_ROW_REVERSE: FlexDirectionValue\n\n  // Wrap\n  WRAP_NO_WRAP: WrapValue\n  WRAP_WRAP: WrapValue\n  WRAP_WRAP_REVERSE: WrapValue\n\n  // Align\n  ALIGN_AUTO: AlignValue\n  ALIGN_FLEX_START: AlignValue\n  ALIGN_CENTER: AlignValue\n  ALIGN_FLEX_END: AlignValue\n  ALIGN_STRETCH: AlignValue\n  ALIGN_BASELINE: AlignValue\n  ALIGN_SPACE_BETWEEN: AlignValue\n  ALIGN_SPACE_AROUND: AlignValue\n  ALIGN_SPACE_EVENLY: AlignValue\n\n  // Justify\n  JUSTIFY_FLEX_START: JustifyValue\n  JUSTIFY_CENTER: JustifyValue\n  JUSTIFY_FLEX_END: JustifyValue\n  JUSTIFY_SPACE_BETWEEN: JustifyValue\n  JUSTIFY_SPACE_AROUND: JustifyValue\n  JUSTIFY_SPACE_EVENLY: JustifyValue\n\n  // Edge\n  EDGE_LEFT: EdgeValue\n  EDGE_TOP: EdgeValue\n  EDGE_RIGHT: EdgeValue\n  EDGE_BOTTOM: EdgeValue\n  EDGE_HORIZONTAL: EdgeValue\n  EDGE_VERTICAL: EdgeValue\n  EDGE_ALL: EdgeValue\n\n  // Gutter\n  GUTTER_COLUMN: GutterValue\n  GUTTER_ROW: GutterValue\n  GUTTER_ALL: GutterValue\n\n  // Display\n  DISPLAY_FLEX: DisplayValue\n  DISPLAY_NONE: DisplayValue\n\n  // Position Type\n  POSITION_TYPE_STATIC: PositionTypeValue\n  POSITION_TYPE_RELATIVE: PositionTypeValue\n  POSITION_TYPE_ABSOLUTE: PositionTypeValue\n\n  // Overflow\n  OVERFLOW_VISIBLE: OverflowValue\n  OVERFLOW_HIDDEN: OverflowValue\n  OVERFLOW_SCROLL: OverflowValue\n\n  // Direction\n  DIRECTION_LTR: DirectionValue\n\n  // Measure Mode\n  MEASURE_MODE_UNDEFINED: MeasureModeValue\n  MEASURE_MODE_EXACTLY: MeasureModeValue\n  MEASURE_MODE_AT_MOST: MeasureModeValue\n}\n\n// ============================================================================\n// Engine Capabilities (Phase A0.0.5 of @km/silvery/responsive-layout-architecture-reframe)\n// ============================================================================\n\n/**\n * Declares which engine-native primitives a `LayoutEngine` supports.\n *\n * silvery is engine-pluggable — `flexily` (pure JS) and `yoga` (WASM) ship as peer\n * adapters. The responsive-layout reframe (Phase A0.1+) adds engine-native container\n * queries, fitWidth, size containment, cq* units, and CSS math functions. These\n * primitives can only be implemented in `flexily` (yoga's WASM boundary doesn't expose\n * inter-pass child-style mutation).\n *\n * Each adapter declares which capabilities it supports. Consumers (`<Box fitWidth>`,\n * `<Box containerQueries>`, etc.) gate on capability presence via `requireCapability()`\n * — under yoga, those primitives THROW at first paint with a one-line fix instruction\n * (switch via `SILVERY_ENGINE=flexily`).\n */\nexport interface EngineCapabilities {\n  /** Container queries: `<Box containerQueries={...}>` + `containerType` / `containerName` */\n  readonly containerQueries: boolean\n  /** Size containment: `<Box containSize>` */\n  readonly containSize: boolean\n  /** Container-query units in style values: `cqi`, `cqmin`, `cqb`, `cqmax` */\n  readonly containerQueryUnits: boolean\n  /** fitWidth Box prop: `<Box fitWidth={[80, 120, \"100cqi\"]}>` */\n  readonly fitWidth: boolean\n  /** CSS math functions in style values: `min()`, `max()`, `clamp()` */\n  readonly styleMathFunctions: boolean\n  /** Inter-pass child-style mutation hook (underlying mechanism for CQ + fitWidth) */\n  readonly childStyleMutation: boolean\n}\n\n// ============================================================================\n// Layout Engine Interface\n// ============================================================================\n\n/**\n * Abstract layout engine interface.\n * Implementations can wrap Yoga, Flexily, or other layout engines.\n */\nexport interface LayoutEngine {\n  /** Create a new layout node */\n  createNode(): LayoutNode\n\n  /** Layout constants for this engine */\n  readonly constants: LayoutConstants\n\n  /** Engine name for debugging */\n  readonly name: string\n\n  /** Which engine-native primitives this adapter supports (Phase A0.0.5+). */\n  readonly capabilities: EngineCapabilities\n}\n\n// ============================================================================\n// Global Layout Engine Management\n// ============================================================================\n\nlet layoutEngine: LayoutEngine | null = null\n\n/**\n * Set the global layout engine instance.\n * Must be called before rendering.\n */\nexport function setLayoutEngine(engine: LayoutEngine): void {\n  layoutEngine = engine\n}\n\n/**\n * Get the global layout engine instance.\n * Throws if not initialized.\n */\nexport function getLayoutEngine(): LayoutEngine {\n  if (!layoutEngine) {\n    throw new Error(\n      \"Layout engine not initialized. Call setLayoutEngine() or initYoga()/initFlexily() first.\",\n    )\n  }\n  return layoutEngine\n}\n\n/**\n * Check if a layout engine is initialized.\n */\nexport function isLayoutEngineInitialized(): boolean {\n  return layoutEngine !== null\n}\n\n/**\n * Get the layout constants from the current engine.\n * Convenience function for accessing constants.\n */\nexport function getConstants(): LayoutConstants {\n  return getLayoutEngine().constants\n}\n\n/**\n * Runtime guard: throws if the active layout engine doesn't advertise the named capability.\n *\n * Used by Phase A0.1+ primitives (`<Box fitWidth>`, `<Box containerQueries>`, cq* units,\n * style math functions) at their first-paint resolution path. Under `yoga` (or pre-A0.1\n * flexily), the throw happens at first paint with a one-line fix instruction in the error\n * message. No silent fallback — silent fallback under yoga would look like a fresh render\n * bug and cost hours of debugging.\n *\n * @param name     The capability key being checked (e.g. `\"fitWidth\"`, `\"containerQueries\"`).\n * @param consumer A human-readable label for the call site, e.g. `\"<Box fitWidth>\"` or\n *                 `\"cqi unit in 'padding'\"`. Surfaces in the error message.\n */\nexport function requireCapability(name: keyof EngineCapabilities, consumer: string): void {\n  const engine = getLayoutEngine()\n  if (!engine.capabilities[name]) {\n    throw new Error(\n      `${consumer} requires layout engine capability \"${name}\" — current engine \"${engine.name}\" doesn't support it. ` +\n        `Switch to flexily: set SILVERY_ENGINE=flexily, OR call ensureDefaultLayoutEngine(\"flexily\") before render.`,\n    )\n  }\n}\n\n// ============================================================================\n// Default Engine Initialization\n// ============================================================================\n\n/**\n * Layout engine type for configuration.\n *\n * - 'flexily': Zero-allocation Flexily (default, optimized for high-frequency layout)\n * - 'flexily-classic': Classic Flexily algorithm (for debugging/compatibility)\n * - 'yoga': Facebook's WASM-based flexbox (most mature)\n */\nexport type LayoutEngineType = \"flexily\" | \"yoga\"\n\n/**\n * Initialize the layout engine if not already set.\n *\n * @param engineType - 'flexily', 'flexily-classic', or 'yoga'. If not provided, checks\n *                     SILVERY_ENGINE env var, then defaults to 'flexily'.\n */\nexport async function ensureDefaultLayoutEngine(engineType?: LayoutEngineType): Promise<void> {\n  if (isLayoutEngineInitialized()) {\n    return\n  }\n\n  // Resolve engine type: option → env → 'flexily'\n  const resolved =\n    engineType ?? (process.env.SILVERY_ENGINE?.toLowerCase() as LayoutEngineType) ?? \"flexily\"\n\n  if (resolved === \"yoga\") {\n    const { initYogaEngine } = await import(\"./adapters/yoga-adapter.js\")\n    setLayoutEngine(await initYogaEngine())\n  } else {\n    // 'flexily' (default) uses zero-allocation engine with CSS-correct defaults\n    const { createFlexilyZeroEngine } = await import(\"./adapters/flexily-zero-adapter.js\")\n    setLayoutEngine(createFlexilyZeroEngine())\n  }\n}\n"],"mappings":";AAwKA,IAAI,eAAoC;;;;;AAMxC,SAAgB,gBAAgB,QAA4B;AAC1D,gBAAe;;;;;;AAOjB,SAAgB,kBAAgC;AAC9C,KAAI,CAAC,aACH,OAAM,IAAI,MACR,2FACD;AAEH,QAAO;;;;;AAMT,SAAgB,4BAAqC;AACnD,QAAO,iBAAiB;;;;;;AAO1B,SAAgB,eAAgC;AAC9C,QAAO,iBAAiB,CAAC;;;;;;;;;;;;;;;AAgB3B,SAAgB,kBAAkB,MAAgC,UAAwB;CACxF,MAAM,SAAS,iBAAiB;AAChC,KAAI,CAAC,OAAO,aAAa,MACvB,OAAM,IAAI,MACR,GAAG,SAAS,sCAAsC,KAAK,sBAAsB,OAAO,KAAK,kIAE1F;;;;;;;;AAuBL,eAAsB,0BAA0B,YAA8C;AAC5F,KAAI,2BAA2B,CAC7B;AAOF,MAFE,cAAe,QAAQ,IAAI,gBAAgB,aAAa,IAAyB,eAElE,QAAQ;EACvB,MAAM,EAAE,mBAAmB,MAAM,OAAO;AACxC,kBAAgB,MAAM,gBAAgB,CAAC;QAClC;EAEL,MAAM,EAAE,4BAA4B,MAAM,OAAO;AACjD,kBAAgB,yBAAyB,CAAC"}

package/dist/{layout-engine-B6Cdz1yZ.mjs → layout-engine-CgsoBRIn.mjs}

@@ -1,2 +1,2 @@
-import { t as ensureDefaultLayoutEngine } from "./layout-engine-ClUgv6jB.mjs";
+import { t as ensureDefaultLayoutEngine } from "./layout-engine-Ca_nbtfL.mjs";
 export { ensureDefaultLayoutEngine };