@pibbl/core 0.0.1 → 0.0.3-alpha.109.1

package/dist/lib/layout/box.js

@@ -1,8 +1,9 @@
+import { contentBoxStyle, borderBoxPaddingFloor } from "./box-sizing.js";
 import {
   layoutDiagnostic
 } from "../style/diagnostics.js";
-import { normalizeEdges } from "../style/normalize.js";
-import { resolveLength } from "../style/resolve-length.js";
+import { normalizeBoxInsets } from "./box-insets.js";
+import { resolveScalarSizingLength } from "../style/sizing-length.js";
 function resolveBox(style, constraints, context = {}) {
   const diagnosticContext = {
     component: context.component ?? "layout",
@@ -10,28 +11,56 @@ function resolveBox(style, constraints, context = {}) {
     constraints
   };
   validateConstraints(constraints, diagnosticContext);
-  const padding = normalizeEdges(style.padding, "padding", diagnosticContext);
+  const ratio = style.aspectRatio;
+  if (ratio !== void 0 && (!Number.isFinite(ratio) || ratio <= 0)) throw layoutDiagnostic({ ...diagnosticContext, property: "aspectRatio", value: ratio, reason: "must be finite and positive" });
+  const paddingFloor = borderBoxPaddingFloor(style);
+  if (style.boxSizing !== void 0) style = contentBoxStyle(style, { width: constraints.maxWidth, height: constraints.maxHeight, context: diagnosticContext });
+  const padding = normalizeBoxInsets(style, diagnosticContext);
+  let width = style.width, height = style.height;
+  const widthAutomatic = width === void 0 || width === "auto";
+  const heightAutomatic = height === void 0 || height === "auto";
+  let vertical;
+  if (ratio !== void 0 && widthAutomatic && !heightAutomatic) {
+    vertical = resolveAxis(
+      "height",
+      height,
+      style.minHeight,
+      style.maxHeight,
+      constraints.minHeight,
+      constraints.maxHeight,
+      padding.top,
+      padding.bottom,
+      diagnosticContext,
+      paddingFloor
+    );
+    width = paddingFloor ? Math.max(0, vertical.border * ratio - padding.left - padding.right) : vertical.content * ratio;
+  }
   const horizontal = resolveAxis(
     "width",
-    style.width,
+    width,
     style.minWidth,
     style.maxWidth,
     constraints.minWidth,
     constraints.maxWidth,
     padding.left,
     padding.right,
-    diagnosticContext
+    diagnosticContext,
+    paddingFloor
   );
-  const vertical = resolveAxis(
+  if (ratio !== void 0 && !widthAutomatic && heightAutomatic) {
+    height = paddingFloor ? Math.max(0, horizontal.border / ratio - padding.top - padding.bottom) : horizontal.content / ratio;
+  }
+  vertical ??= resolveAxis(
     "height",
-    style.height,
+    height,
     style.minHeight,
     style.maxHeight,
     constraints.minHeight,
     constraints.maxHeight,
     padding.top,
     padding.bottom,
-    diagnosticContext
+    diagnosticContext,
+    paddingFloor
   );
   return {
     borderBox: {
@@ -48,7 +77,7 @@ function resolveBox(style, constraints, context = {}) {
     }
   };
 }
-function resolveAxis(axis, specified, specifiedMinimum, specifiedMaximum, constraintMinimum, constraintMaximum, paddingStart, paddingEnd, context) {
+function resolveAxis(axis, specified, specifiedMinimum, specifiedMaximum, constraintMinimum, constraintMaximum, paddingStart, paddingEnd, context, paddingFloor) {
   const minimumProperty = axis === "width" ? "minWidth" : "minHeight";
   const maximumProperty = axis === "width" ? "maxWidth" : "maxHeight";
   const minimum = specifiedMinimum === void 0 ? 0 : resolveAllocationLength(
@@ -76,7 +105,7 @@ function resolveAxis(axis, specified, specifiedMinimum, specifiedMaximum, constr
     axis,
     context
   );
-  const resolved = specified === void 0 ? void 0 : resolveLength(specified, constraintMaximum, axis, context);
+  const resolved = specified === void 0 ? void 0 : resolveScalarSizingLength(specified, constraintMaximum, axis, context);
   let content;
   if (resolved === void 0) {
     if (!Number.isFinite(constraintMaximum)) {
@@ -108,10 +137,11 @@ function resolveAxis(axis, specified, specifiedMinimum, specifiedMaximum, constr
     axis,
     context
   );
-  const border = Math.min(
+  const constrainedBorder = Math.min(
     constraintMaximum,
     Math.max(constraintMinimum, paddedContent)
   );
+  const border = paddingFloor ? Math.max(padding, constrainedBorder) : constrainedBorder;
   return {
     border: requireFiniteArithmetic(border, axis, context),
     content: Math.max(
@@ -132,7 +162,7 @@ function requireFiniteArithmetic(value, property, context) {
   return value;
 }
 function resolveAllocationLength(value, reference, property, context) {
-  const resolved = resolveLength(value, reference, property, context);
+  const resolved = resolveScalarSizingLength(value, reference, property, context);
   if (resolved < 0) {
     throw layoutDiagnostic({
       ...context,

package/dist/lib/layout/box.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/layout/box.ts"],
-  "sourcesContent": ["import {\n  layoutDiagnostic,\n  type LayoutDiagnosticContext,\n} from '../style/diagnostics.js';\nimport { normalizeEdges } from '../style/normalize.js';\nimport { resolveLength } from '../style/resolve-length.js';\nimport type { BoxStyle, Length, ResolvedBoxStyle } from '../style/types.js';\nimport type { Constraints } from './types.js';\n\n/**\n * Resolves declared box sizing and padding into border and content boxes under parent constraints.\n *\n * @param style - Declared box sizing and edge properties. See {@link BoxStyle}.\n * @param constraints - Available dimensions used to resolve percentages and constraints. See\n * {@link Constraints} .\n * @param context - Component and property context for diagnostic messages. See\n * {@link LayoutDiagnosticContext} .\n * @returns Resolved box dimensions and edge values. See {@link ResolvedBoxStyle}.\n *\n * @see {@link BoxStyle}\n * @see {@link Constraints}\n * @see {@link LayoutDiagnosticContext}\n * @see {@link ResolvedBoxStyle}\n */\nexport function resolveBox(\n  style: Readonly<BoxStyle>,\n  constraints: Readonly<Constraints>,\n  context: Readonly<LayoutDiagnosticContext> = {},\n): ResolvedBoxStyle {\n  const diagnosticContext = {\n    component: context.component ?? 'layout',\n    algorithm: context.algorithm ?? 'box-resolution',\n    constraints,\n  };\n  validateConstraints(constraints, diagnosticContext);\n  const padding = normalizeEdges(style.padding, 'padding', diagnosticContext);\n\n  const horizontal = resolveAxis(\n    'width',\n    style.width,\n    style.minWidth,\n    style.maxWidth,\n    constraints.minWidth,\n    constraints.maxWidth,\n    padding.left,\n    padding.right,\n    diagnosticContext,\n  );\n  const vertical = resolveAxis(\n    'height',\n    style.height,\n    style.minHeight,\n    style.maxHeight,\n    constraints.minHeight,\n    constraints.maxHeight,\n    padding.top,\n    padding.bottom,\n    diagnosticContext,\n  );\n\n  return {\n    borderBox: {\n      x: 0,\n      y: 0,\n      width: horizontal.border,\n      height: vertical.border,\n    },\n    contentBox: {\n      x: padding.left,\n      y: padding.top,\n      width: horizontal.content,\n      height: vertical.content,\n    },\n  };\n}\n\nfunction resolveAxis(\n  axis: 'width' | 'height',\n  specified: Length | undefined,\n  specifiedMinimum: Exclude<Length, 'auto'> | undefined,\n  specifiedMaximum: Exclude<Length, 'auto'> | undefined,\n  constraintMinimum: number,\n  constraintMaximum: number,\n  paddingStart: number,\n  paddingEnd: number,\n  context: Readonly<LayoutDiagnosticContext>,\n): { border: number; content: number } {\n  const minimumProperty = axis === 'width' ? 'minWidth' : 'minHeight';\n  const maximumProperty = axis === 'width' ? 'maxWidth' : 'maxHeight';\n  const minimum =\n    specifiedMinimum === undefined\n      ? 0\n      : resolveAllocationLength(\n          specifiedMinimum,\n          constraintMaximum,\n          minimumProperty,\n          context,\n        );\n  const maximum =\n    specifiedMaximum === undefined\n      ? Number.POSITIVE_INFINITY\n      : resolveAllocationLength(\n          specifiedMaximum,\n          constraintMaximum,\n          maximumProperty,\n          context,\n        );\n\n  if (minimum > maximum) {\n    throw layoutDiagnostic({\n      ...context,\n      property: minimumProperty,\n      value: minimum,\n      reason: `${minimumProperty} ${minimum} must not exceed ${maximumProperty} ${maximum}`,\n    });\n  }\n\n  const padding = requireFiniteArithmetic(\n    paddingStart + paddingEnd,\n    axis,\n    context,\n  );\n  const resolved =\n    specified === undefined\n      ? undefined\n      : resolveLength(specified, constraintMaximum, axis, context);\n  let content: number;\n  if (resolved === undefined) {\n    if (!Number.isFinite(constraintMaximum)) {\n      throw layoutDiagnostic({\n        ...context,\n        property: axis,\n        value: specified ?? 'auto',\n        reason: 'requires a definite finite allocation for auto sizing',\n      });\n    }\n    content = Math.max(\n      0,\n      requireFiniteArithmetic(constraintMaximum - padding, axis, context),\n    );\n  } else {\n    if (resolved < 0) {\n      throw layoutDiagnostic({\n        ...context,\n        property: axis,\n        value: specified,\n        reason: 'must be nonnegative when used as a layout allocation',\n      });\n    }\n    content = resolved;\n  }\n\n  content = Math.min(maximum, Math.max(minimum, content));\n  const paddedContent = requireFiniteArithmetic(\n    content + padding,\n    axis,\n    context,\n  );\n  const border = Math.min(\n    constraintMaximum,\n    Math.max(constraintMinimum, paddedContent),\n  );\n  return {\n    border: requireFiniteArithmetic(border, axis, context),\n    content: Math.max(\n      0,\n      requireFiniteArithmetic(border - padding, axis, context),\n    ),\n  };\n}\n\nfunction requireFiniteArithmetic(\n  value: number,\n  property: string,\n  context: Readonly<LayoutDiagnosticContext>,\n): number {\n  if (!Number.isFinite(value)) {\n    throw layoutDiagnostic({\n      ...context,\n      property,\n      value,\n      reason: 'resolved box arithmetic must remain finite',\n    });\n  }\n  return value;\n}\n\nfunction resolveAllocationLength(\n  value: Exclude<Length, 'auto'>,\n  reference: number,\n  property: string,\n  context: Readonly<LayoutDiagnosticContext>,\n): number {\n  const resolved = resolveLength(value, reference, property, context)!;\n  if (resolved < 0) {\n    throw layoutDiagnostic({\n      ...context,\n      property,\n      value,\n      reason: 'must be nonnegative when used as a layout allocation',\n    });\n  }\n  return resolved;\n}\n\nfunction validateConstraints(\n  constraints: Readonly<Constraints>,\n  context: Readonly<LayoutDiagnosticContext>,\n): void {\n  validateConstraint(\n    constraints.minWidth,\n    'constraints.minWidth',\n    false,\n    context,\n  );\n  validateConstraint(\n    constraints.maxWidth,\n    'constraints.maxWidth',\n    true,\n    context,\n  );\n  validateConstraint(\n    constraints.minHeight,\n    'constraints.minHeight',\n    false,\n    context,\n  );\n  validateConstraint(\n    constraints.maxHeight,\n    'constraints.maxHeight',\n    true,\n    context,\n  );\n\n  if (constraints.minWidth > constraints.maxWidth) {\n    throw layoutDiagnostic({\n      ...context,\n      property: 'constraints.minWidth',\n      value: constraints.minWidth,\n      reason: `constraints.minWidth ${constraints.minWidth} must not exceed constraints.maxWidth ${constraints.maxWidth}`,\n    });\n  }\n  if (constraints.minHeight > constraints.maxHeight) {\n    throw layoutDiagnostic({\n      ...context,\n      property: 'constraints.minHeight',\n      value: constraints.minHeight,\n      reason: `constraints.minHeight ${constraints.minHeight} must not exceed constraints.maxHeight ${constraints.maxHeight}`,\n    });\n  }\n}\n\nfunction validateConstraint(\n  value: number,\n  property: string,\n  allowPositiveInfinity: boolean,\n  context: Readonly<LayoutDiagnosticContext>,\n): void {\n  if (\n    !Number.isFinite(value) &&\n    !(allowPositiveInfinity && value === Number.POSITIVE_INFINITY)\n  ) {\n    throw layoutDiagnostic({\n      ...context,\n      property,\n      value,\n      reason: 'must be finite',\n    });\n  }\n  if (value < 0) {\n    throw layoutDiagnostic({\n      ...context,\n      property,\n      value,\n      reason: 'must be nonnegative',\n    });\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import { contentBoxStyle, borderBoxPaddingFloor } from './box-sizing.js';\nimport {\n  layoutDiagnostic,\n  type LayoutDiagnosticContext,\n} from '../style/diagnostics.js';\nimport { normalizeBoxInsets } from './box-insets.js';\nimport { resolveScalarSizingLength } from '../style/sizing-length.js';\nimport type { BoxStyle, ResolvedBoxStyle } from '../style/types.js';\nimport type { SizingLength } from '../style/sizing-length.js';\nimport type { Constraints } from './types.js';\n\n/**\n * Resolves declared box sizing and padding into border and content boxes under parent constraints.\n *\n * @param style - Declared box sizing and edge properties. See {@link BoxStyle}.\n * @param constraints - Available dimensions used to resolve percentages and constraints. See\n * {@link Constraints} .\n * @param context - Component and property context for diagnostic messages. See\n * {@link LayoutDiagnosticContext} .\n * @returns Resolved box dimensions and edge values. See {@link ResolvedBoxStyle}.\n *\n * @see {@link BoxStyle}\n * @see {@link Constraints}\n * @see {@link LayoutDiagnosticContext}\n * @see {@link ResolvedBoxStyle}\n */\nexport function resolveBox(\n  style: Readonly<BoxStyle>,\n  constraints: Readonly<Constraints>,\n  context: Readonly<LayoutDiagnosticContext> = {},\n): ResolvedBoxStyle {\n  const diagnosticContext = {\n    component: context.component ?? 'layout',\n    algorithm: context.algorithm ?? 'box-resolution',\n    constraints,\n  };\n  validateConstraints(constraints, diagnosticContext);\n  const ratio = style.aspectRatio;\n  if (ratio !== undefined && (!Number.isFinite(ratio) || ratio <= 0)) throw layoutDiagnostic({ ...diagnosticContext, property: 'aspectRatio', value: ratio, reason: 'must be finite and positive' });\n  const paddingFloor = borderBoxPaddingFloor(style);\n  if (style.boxSizing !== undefined) style = contentBoxStyle(style, { width: constraints.maxWidth, height: constraints.maxHeight, context: diagnosticContext });\n  const padding = normalizeBoxInsets(style, diagnosticContext);\n\n  let width = style.width, height = style.height;\n  const widthAutomatic = width === undefined || width === 'auto';\n  const heightAutomatic = height === undefined || height === 'auto';\n  let vertical: { border: number; content: number } | undefined;\n  if (ratio !== undefined && widthAutomatic && !heightAutomatic) {\n    vertical = resolveAxis('height', height, style.minHeight, style.maxHeight,\n      constraints.minHeight, constraints.maxHeight, padding.top, padding.bottom, diagnosticContext, paddingFloor);\n    width = paddingFloor ? Math.max(0, vertical.border * ratio - padding.left - padding.right) : vertical.content * ratio;\n  }\n  const horizontal = resolveAxis(\n    'width',\n    width,\n    style.minWidth,\n    style.maxWidth,\n    constraints.minWidth,\n    constraints.maxWidth,\n    padding.left,\n    padding.right,\n    diagnosticContext,\n    paddingFloor,\n  );\n  if (ratio !== undefined && !widthAutomatic && heightAutomatic) {\n    height = paddingFloor ? Math.max(0, horizontal.border / ratio - padding.top - padding.bottom) : horizontal.content / ratio;\n  }\n  vertical ??= resolveAxis(\n    'height',\n    height,\n    style.minHeight,\n    style.maxHeight,\n    constraints.minHeight,\n    constraints.maxHeight,\n    padding.top,\n    padding.bottom,\n    diagnosticContext,\n    paddingFloor,\n  );\n\n  return {\n    borderBox: {\n      x: 0,\n      y: 0,\n      width: horizontal.border,\n      height: vertical.border,\n    },\n    contentBox: {\n      x: padding.left,\n      y: padding.top,\n      width: horizontal.content,\n      height: vertical.content,\n    },\n  };\n}\n\nfunction resolveAxis(\n  axis: 'width' | 'height',\n  specified: SizingLength | undefined,\n  specifiedMinimum: Exclude<SizingLength, 'auto'> | undefined,\n  specifiedMaximum: Exclude<SizingLength, 'auto'> | undefined,\n  constraintMinimum: number,\n  constraintMaximum: number,\n  paddingStart: number,\n  paddingEnd: number,\n  context: Readonly<LayoutDiagnosticContext>,\n  paddingFloor: boolean,\n): { border: number; content: number } {\n  const minimumProperty = axis === 'width' ? 'minWidth' : 'minHeight';\n  const maximumProperty = axis === 'width' ? 'maxWidth' : 'maxHeight';\n  const minimum =\n    specifiedMinimum === undefined\n      ? 0\n      : resolveAllocationLength(\n          specifiedMinimum,\n          constraintMaximum,\n          minimumProperty,\n          context,\n        );\n  const maximum =\n    specifiedMaximum === undefined\n      ? Number.POSITIVE_INFINITY\n      : resolveAllocationLength(\n          specifiedMaximum,\n          constraintMaximum,\n          maximumProperty,\n          context,\n        );\n\n  if (minimum > maximum) {\n    throw layoutDiagnostic({\n      ...context,\n      property: minimumProperty,\n      value: minimum,\n      reason: `${minimumProperty} ${minimum} must not exceed ${maximumProperty} ${maximum}`,\n    });\n  }\n\n  const padding = requireFiniteArithmetic(\n    paddingStart + paddingEnd,\n    axis,\n    context,\n  );\n  const resolved =\n    specified === undefined\n      ? undefined\n      : resolveScalarSizingLength(specified, constraintMaximum, axis, context);\n  let content: number;\n  if (resolved === undefined) {\n    if (!Number.isFinite(constraintMaximum)) {\n      throw layoutDiagnostic({\n        ...context,\n        property: axis,\n        value: specified ?? 'auto',\n        reason: 'requires a definite finite allocation for auto sizing',\n      });\n    }\n    content = Math.max(\n      0,\n      requireFiniteArithmetic(constraintMaximum - padding, axis, context),\n    );\n  } else {\n    if (resolved < 0) {\n      throw layoutDiagnostic({\n        ...context,\n        property: axis,\n        value: specified,\n        reason: 'must be nonnegative when used as a layout allocation',\n      });\n    }\n    content = resolved;\n  }\n\n  content = Math.min(maximum, Math.max(minimum, content));\n  const paddedContent = requireFiniteArithmetic(\n    content + padding,\n    axis,\n    context,\n  );\n  const constrainedBorder = Math.min(\n    constraintMaximum,\n    Math.max(constraintMinimum, paddedContent),\n  );\n  const border = paddingFloor ? Math.max(padding, constrainedBorder) : constrainedBorder;\n  return {\n    border: requireFiniteArithmetic(border, axis, context),\n    content: Math.max(\n      0,\n      requireFiniteArithmetic(border - padding, axis, context),\n    ),\n  };\n}\n\nfunction requireFiniteArithmetic(\n  value: number,\n  property: string,\n  context: Readonly<LayoutDiagnosticContext>,\n): number {\n  if (!Number.isFinite(value)) {\n    throw layoutDiagnostic({\n      ...context,\n      property,\n      value,\n      reason: 'resolved box arithmetic must remain finite',\n    });\n  }\n  return value;\n}\n\nfunction resolveAllocationLength(\n  value: Exclude<SizingLength, 'auto'>,\n  reference: number,\n  property: string,\n  context: Readonly<LayoutDiagnosticContext>,\n): number {\n  const resolved = resolveScalarSizingLength(value, reference, property, context)!;\n  if (resolved < 0) {\n    throw layoutDiagnostic({\n      ...context,\n      property,\n      value,\n      reason: 'must be nonnegative when used as a layout allocation',\n    });\n  }\n  return resolved;\n}\n\nfunction validateConstraints(\n  constraints: Readonly<Constraints>,\n  context: Readonly<LayoutDiagnosticContext>,\n): void {\n  validateConstraint(\n    constraints.minWidth,\n    'constraints.minWidth',\n    false,\n    context,\n  );\n  validateConstraint(\n    constraints.maxWidth,\n    'constraints.maxWidth',\n    true,\n    context,\n  );\n  validateConstraint(\n    constraints.minHeight,\n    'constraints.minHeight',\n    false,\n    context,\n  );\n  validateConstraint(\n    constraints.maxHeight,\n    'constraints.maxHeight',\n    true,\n    context,\n  );\n\n  if (constraints.minWidth > constraints.maxWidth) {\n    throw layoutDiagnostic({\n      ...context,\n      property: 'constraints.minWidth',\n      value: constraints.minWidth,\n      reason: `constraints.minWidth ${constraints.minWidth} must not exceed constraints.maxWidth ${constraints.maxWidth}`,\n    });\n  }\n  if (constraints.minHeight > constraints.maxHeight) {\n    throw layoutDiagnostic({\n      ...context,\n      property: 'constraints.minHeight',\n      value: constraints.minHeight,\n      reason: `constraints.minHeight ${constraints.minHeight} must not exceed constraints.maxHeight ${constraints.maxHeight}`,\n    });\n  }\n}\n\nfunction validateConstraint(\n  value: number,\n  property: string,\n  allowPositiveInfinity: boolean,\n  context: Readonly<LayoutDiagnosticContext>,\n): void {\n  if (\n    !Number.isFinite(value) &&\n    !(allowPositiveInfinity && value === Number.POSITIVE_INFINITY)\n  ) {\n    throw layoutDiagnostic({\n      ...context,\n      property,\n      value,\n      reason: 'must be finite',\n    });\n  }\n  if (value < 0) {\n    throw layoutDiagnostic({\n      ...context,\n      property,\n      value,\n      reason: 'must be nonnegative',\n    });\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/lib/layout/canvas-measurement.d.ts

@@ -0,0 +1,13 @@
+import type { RenderingContext2D, CanvasMeasurementService } from '../types.js';
+/** Matches the existing retained Text metric policy; application faces are external inputs. */
+export declare function isGenericCanvasFont(font: string): boolean;
+/** @internal Pure Canvas metrics with explicit state isolation. */
+export declare function canvasMeasurementService(context: RenderingContext2D): CanvasMeasurementService;
+/** Internal wrappers are equivalent only when they target the same Canvas.
+ * Pure measurement clears render state, so compare the bound targets directly.
+ * Independent custom services retain strict identity semantics.
+ */
+export declare function sameCanvasMeasurementService(left: CanvasMeasurementService, right: CanvasMeasurementService): boolean;
+export declare function isCurrentCanvasMeasurementService(service: CanvasMeasurementService): boolean;
+/** Avoid retaining a previous frame's temporary Canvas measurement target. */
+export declare function bindCanvasMeasurementService(service: CanvasMeasurementService): () => CanvasMeasurementService;

package/dist/lib/layout/canvas-measurement.js

@@ -0,0 +1,57 @@
+import { markVolatileAllocationQuery } from "./allocation-checkpoint.js";
+import { GLOBAL_STATE } from "../global-state.js";
+function isGenericCanvasFont(font) {
+  return /^(?:(?:bold|italic|normal) )?\d+(?:\.\d+)?px (?:sans-serif|serif|monospace)$/.test(font);
+}
+const serviceContexts = /* @__PURE__ */ new WeakMap();
+function canvasMeasurementService(context) {
+  const service = {
+    measureText(text, font) {
+      if (!isGenericCanvasFont(font)) markVolatileAllocationQuery();
+      context.save();
+      try {
+        context.font = font;
+        return context.measureText(text);
+      } finally {
+        context.restore();
+      }
+    },
+    measureTextAtBaseline(text, options) {
+      if (!isGenericCanvasFont(options.font)) markVolatileAllocationQuery();
+      context.save();
+      try {
+        context.font = options.font;
+        context.textBaseline = options.textBaseline;
+        return context.measureText(text);
+      } finally {
+        context.restore();
+      }
+    }
+  };
+  serviceContexts.set(service, context);
+  return service;
+}
+function sameCanvasMeasurementService(left, right) {
+  if (left === right) return true;
+  const context = serviceContexts.get(left);
+  return context !== void 0 && context === serviceContexts.get(right);
+}
+function isCurrentCanvasMeasurementService(service) {
+  return GLOBAL_STATE.renderContext !== void 0 && serviceContexts.get(service) === GLOBAL_STATE.renderContext;
+}
+function currentCanvasMeasurementService() {
+  const context = GLOBAL_STATE.renderContext;
+  if (!context) throw new Error("A mounted measurement replay requires its current Canvas context.");
+  return canvasMeasurementService(context);
+}
+function bindCanvasMeasurementService(service) {
+  return isCurrentCanvasMeasurementService(service) ? currentCanvasMeasurementService : () => service;
+}
+export {
+  bindCanvasMeasurementService,
+  canvasMeasurementService,
+  isCurrentCanvasMeasurementService,
+  isGenericCanvasFont,
+  sameCanvasMeasurementService
+};
+//# sourceMappingURL=canvas-measurement.js.map

package/dist/lib/layout/canvas-measurement.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/layout/canvas-measurement.ts"],
+  "sourcesContent": ["import { markVolatileAllocationQuery } from './allocation-checkpoint.js';\nimport { GLOBAL_STATE } from '../global-state.js';\nimport type { RenderingContext2D, CanvasMeasurementService } from '../types.js';\n\n/** Matches the existing retained Text metric policy; application faces are external inputs. */\nexport function isGenericCanvasFont(font: string): boolean {\n  return /^(?:(?:bold|italic|normal) )?\\d+(?:\\.\\d+)?px (?:sans-serif|serif|monospace)$/.test(font);\n}\n\nconst serviceContexts = new WeakMap<CanvasMeasurementService, RenderingContext2D>();\n\n/** @internal Pure Canvas metrics with explicit state isolation. */\nexport function canvasMeasurementService(\n  context: RenderingContext2D,\n): CanvasMeasurementService {\n  const service: CanvasMeasurementService = {\n    measureText(text: string, font: string): TextMetrics {\n      if (!isGenericCanvasFont(font)) markVolatileAllocationQuery();\n      context.save();\n      try {\n        context.font = font;\n        return context.measureText(text);\n      } finally {\n        context.restore();\n      }\n    },\n    measureTextAtBaseline(\n      text: string,\n      options: Readonly<{ font: string; textBaseline: CanvasTextBaseline }>,\n    ): TextMetrics {\n      if (!isGenericCanvasFont(options.font)) markVolatileAllocationQuery();\n      context.save();\n      try {\n        context.font = options.font;\n        context.textBaseline = options.textBaseline;\n        return context.measureText(text);\n      } finally {\n        context.restore();\n      }\n    },\n  };\n  serviceContexts.set(service, context);\n  return service;\n}\n\n/** Internal wrappers are equivalent only when they target the same Canvas.\n * Pure measurement clears render state, so compare the bound targets directly.\n * Independent custom services retain strict identity semantics.\n */\nexport function sameCanvasMeasurementService(left: CanvasMeasurementService, right: CanvasMeasurementService): boolean {\n  if (left === right) return true;\n  const context = serviceContexts.get(left);\n  return context !== undefined && context === serviceContexts.get(right);\n}\n\nexport function isCurrentCanvasMeasurementService(service: CanvasMeasurementService): boolean {\n  return GLOBAL_STATE.renderContext !== undefined && serviceContexts.get(service) === GLOBAL_STATE.renderContext;\n}\nfunction currentCanvasMeasurementService(): CanvasMeasurementService {\n  const context = GLOBAL_STATE.renderContext;\n  if (!context) throw new Error('A mounted measurement replay requires its current Canvas context.');\n  return canvasMeasurementService(context);\n}\n/** Avoid retaining a previous frame's temporary Canvas measurement target. */\nexport function bindCanvasMeasurementService(service: CanvasMeasurementService): () => CanvasMeasurementService {\n  return isCurrentCanvasMeasurementService(service) ? currentCanvasMeasurementService : () => service;\n}\n"],
+  "mappings": "AAAA,SAAS,mCAAmC;AAC5C,SAAS,oBAAoB;AAItB,SAAS,oBAAoB,MAAuB;AACzD,SAAO,+EAA+E,KAAK,IAAI;AACjG;AAEA,MAAM,kBAAkB,oBAAI,QAAsD;AAG3E,SAAS,yBACd,SAC0B;AAC1B,QAAM,UAAoC;AAAA,IACxC,YAAY,MAAc,MAA2B;AACnD,UAAI,CAAC,oBAAoB,IAAI,EAAG,6BAA4B;AAC5D,cAAQ,KAAK;AACb,UAAI;AACF,gBAAQ,OAAO;AACf,eAAO,QAAQ,YAAY,IAAI;AAAA,MACjC,UAAE;AACA,gBAAQ,QAAQ;AAAA,MAClB;AAAA,IACF;AAAA,IACA,sBACE,MACA,SACa;AACb,UAAI,CAAC,oBAAoB,QAAQ,IAAI,EAAG,6BAA4B;AACpE,cAAQ,KAAK;AACb,UAAI;AACF,gBAAQ,OAAO,QAAQ;AACvB,gBAAQ,eAAe,QAAQ;AAC/B,eAAO,QAAQ,YAAY,IAAI;AAAA,MACjC,UAAE;AACA,gBAAQ,QAAQ;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AACA,kBAAgB,IAAI,SAAS,OAAO;AACpC,SAAO;AACT;AAMO,SAAS,6BAA6B,MAAgC,OAA0C;AACrH,MAAI,SAAS,MAAO,QAAO;AAC3B,QAAM,UAAU,gBAAgB,IAAI,IAAI;AACxC,SAAO,YAAY,UAAa,YAAY,gBAAgB,IAAI,KAAK;AACvE;AAEO,SAAS,kCAAkC,SAA4C;AAC5F,SAAO,aAAa,kBAAkB,UAAa,gBAAgB,IAAI,OAAO,MAAM,aAAa;AACnG;AACA,SAAS,kCAA4D;AACnE,QAAM,UAAU,aAAa;AAC7B,MAAI,CAAC,QAAS,OAAM,IAAI,MAAM,mEAAmE;AACjG,SAAO,yBAAyB,OAAO;AACzC;AAEO,SAAS,6BAA6B,SAAmE;AAC9G,SAAO,kCAAkC,OAAO,IAAI,kCAAkC,MAAM;AAC9F;",
+  "names": []
+}

package/dist/lib/layout/context.d.ts

@@ -1,13 +1,42 @@
-import type { LayoutBox } from './types.js';
+import type { BoxStyle } from "../style/types.js";
+import type { LayoutBox } from "./types.js";
+/** @internal A pushed allocation remains active through ordinary components. */
+export declare function hasParentLayoutAllocation(): boolean;
+/** @internal Inherited inline direction; roots default to LTR. */
+export declare function getLayoutDirection(): "ltr" | "rtl";
 export declare function getLayoutBox(): Readonly<LayoutBox>;
 export declare function getPercentageBasis(): Readonly<LayoutBox>;
+/** @internal Current accumulated layout origin, before Canvas presentation transforms. */
+export declare function getLogicalLayoutOrigin(): Readonly<{
+    x: number;
+    y: number;
+}>;
+/** The nearest positioned layout box, expressed before presentation transforms. */
+export declare function getLogicalContainingBox(): Readonly<LayoutBox>;
 /**
- * Pushes a layout allocation for nested evaluation and returns the callback that restores the
- * previous allocation.
+ * Resolves the positioned containing block in the current layout coordinates.
+ * A positioned layout boundary owns its padding box; a static boundary stays
+ * transparent and inherits the nearest positioned ancestor.
  *
- * @param box - Parent allocation to expose to child layout hooks. See {@link LayoutBox}.
- * @returns A function restoring the previous layout box.
+ * @internal
+ */
+export declare function resolvePositionedContainingBox(style: Readonly<BoxStyle & {
+    readonly position?: string;
+}>, content: Readonly<LayoutBox>, component: string): Readonly<LayoutBox> | undefined;
+/**
+ * Pushes one finite layout allocation and returns its exact restoration callback.
+ *
+ * @param box - Child allocation to expose during nested layout work.
+ * @param options - Optional inherited direction and containing-block metadata.
+ * @returns A callback that restores the prior layout context.
  *
  * @see {@link LayoutBox}
  */
-export declare function pushLayoutBox(box: Readonly<LayoutBox>): () => void;
+export declare function pushLayoutBox(box: Readonly<LayoutBox>, options?: {
+    readonly layoutDirection?: "ltr" | "rtl";
+    readonly logicalOffset?: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    readonly containingBlock?: Readonly<LayoutBox>;
+}): () => void;

package/dist/lib/layout/context.js

@@ -1,4 +1,11 @@
 import { GLOBAL_STATE } from "../global-state.js";
+import { normalizePaddingInsets } from "./box-insets.js";
+function hasParentLayoutAllocation() {
+  return (GLOBAL_STATE.layoutStack?.length ?? 0) > 1;
+}
+function getLayoutDirection() {
+  return GLOBAL_STATE.layoutStack?.at(-1)?.layoutDirection ?? "ltr";
+}
 function getLayoutBox() {
   const context = GLOBAL_STATE.layoutStack?.at(-1);
   if (!context) {
@@ -13,7 +20,46 @@ function getPercentageBasis() {
   }
   return context.percentageBasis;
 }
-function pushLayoutBox(box) {
+const logicalContexts = /* @__PURE__ */ new WeakMap();
+const ROOT_LOGICAL_ORIGIN = Object.freeze({ x: 0, y: 0 });
+function getLogicalLayoutOrigin() {
+  const context = GLOBAL_STATE.layoutStack?.at(-1);
+  if (!context) throw new Error("No Pibbl layout context is available");
+  return logicalContexts.get(context) ?? ROOT_LOGICAL_ORIGIN;
+}
+function getLogicalContainingBox() {
+  const context = GLOBAL_STATE.layoutStack?.at(-1);
+  if (!context)
+    throw new Error("No Pibbl containing layout context is available");
+  const logical = logicalContexts.get(context);
+  if (!logical) return context.allocation;
+  return {
+    x: logical.containing.x - logical.x,
+    y: logical.containing.y - logical.y,
+    width: logical.containing.width,
+    height: logical.containing.height
+  };
+}
+function resolvePositionedContainingBox(style, content, component) {
+  if (style.position === "static") return void 0;
+  const padding = normalizePaddingInsets(style, {
+    component,
+    algorithm: "containing block",
+    constraints: {
+      minWidth: 0,
+      maxWidth: content.width,
+      minHeight: 0,
+      maxHeight: content.height
+    }
+  });
+  return Object.freeze({
+    x: content.x - padding.left,
+    y: content.y - padding.top,
+    width: content.width + padding.left + padding.right,
+    height: content.height + padding.top + padding.bottom
+  });
+}
+function pushLayoutBox(box, options) {
   const stack = GLOBAL_STATE.layoutStack;
   if (!stack) {
     throw new Error("No Pibbl layout context is available");
@@ -22,7 +68,25 @@ function pushLayoutBox(box) {
   if (!parent) {
     throw new Error("No Pibbl parent layout context is available");
   }
-  const context = { allocation: box, percentageBasis: parent.allocation };
+  const context = {
+    allocation: box,
+    percentageBasis: parent.allocation,
+    layoutDirection: options?.layoutDirection ?? parent.layoutDirection ?? "ltr"
+  };
+  const inherited = logicalContexts.get(parent);
+  const x = (inherited?.x ?? 0) + (options?.logicalOffset?.x ?? 0);
+  const y = (inherited?.y ?? 0) + (options?.logicalOffset?.y ?? 0);
+  const declared = options?.containingBlock;
+  logicalContexts.set(context, {
+    x,
+    y,
+    containing: declared ? {
+      x: x + declared.x,
+      y: y + declared.y,
+      width: declared.width,
+      height: declared.height
+    } : inherited?.containing ?? parent.allocation
+  });
   stack.push(context);
   let active = true;
   return () => {
@@ -36,7 +100,12 @@ function pushLayoutBox(box) {
 }
 export {
   getLayoutBox,
+  getLayoutDirection,
+  getLogicalContainingBox,
+  getLogicalLayoutOrigin,
   getPercentageBasis,
-  pushLayoutBox
+  hasParentLayoutAllocation,
+  pushLayoutBox,
+  resolvePositionedContainingBox
 };
 //# sourceMappingURL=context.js.map

package/dist/lib/layout/context.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/layout/context.ts"],
-  "sourcesContent": ["import { GLOBAL_STATE } from '../global-state.js';\nimport type { LayoutBox } from './types.js';\n\nexport function getLayoutBox(): Readonly<LayoutBox> {\n  const context = GLOBAL_STATE.layoutStack?.at(-1);\n  if (!context) {\n    throw new Error('No Pibbl layout context is available');\n  }\n  return context.allocation;\n}\n\nexport function getPercentageBasis(): Readonly<LayoutBox> {\n  const context = GLOBAL_STATE.layoutStack?.at(-1);\n  if (!context) {\n    throw new Error('No Pibbl layout context is available');\n  }\n  return context.percentageBasis;\n}\n\n/**\n * Pushes a layout allocation for nested evaluation and returns the callback that restores the\n * previous allocation.\n *\n * @param box - Parent allocation to expose to child layout hooks. See {@link LayoutBox}.\n * @returns A function restoring the previous layout box.\n *\n * @see {@link LayoutBox}\n */\nexport function pushLayoutBox(box: Readonly<LayoutBox>): () => void {\n  const stack = GLOBAL_STATE.layoutStack;\n  if (!stack) {\n    throw new Error('No Pibbl layout context is available');\n  }\n  const parent = stack.at(-1);\n  if (!parent) {\n    throw new Error('No Pibbl parent layout context is available');\n  }\n  const context = { allocation: box, percentageBasis: parent.allocation };\n  stack.push(context);\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    if (stack.at(-1) !== context) {\n      throw new Error('Pibbl layout context was restored out of order');\n    }\n    stack.pop();\n  };\n}\n"],
-  "mappings": "AAAA,SAAS,oBAAoB;AAGtB,SAAS,eAAoC;AAClD,QAAM,UAAU,aAAa,aAAa,GAAG,EAAE;AAC/C,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,sCAAsC;AAAA,EACxD;AACA,SAAO,QAAQ;AACjB;AAEO,SAAS,qBAA0C;AACxD,QAAM,UAAU,aAAa,aAAa,GAAG,EAAE;AAC/C,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,sCAAsC;AAAA,EACxD;AACA,SAAO,QAAQ;AACjB;AAWO,SAAS,cAAc,KAAsC;AAClE,QAAM,QAAQ,aAAa;AAC3B,MAAI,CAAC,OAAO;AACV,UAAM,IAAI,MAAM,sCAAsC;AAAA,EACxD;AACA,QAAM,SAAS,MAAM,GAAG,EAAE;AAC1B,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,6CAA6C;AAAA,EAC/D;AACA,QAAM,UAAU,EAAE,YAAY,KAAK,iBAAiB,OAAO,WAAW;AACtE,QAAM,KAAK,OAAO;AAClB,MAAI,SAAS;AACb,SAAO,MAAM;AACX,QAAI,CAAC,OAAQ;AACb,aAAS;AACT,QAAI,MAAM,GAAG,EAAE,MAAM,SAAS;AAC5B,YAAM,IAAI,MAAM,gDAAgD;AAAA,IAClE;AACA,UAAM,IAAI;AAAA,EACZ;AACF;",
+  "sourcesContent": ["import { GLOBAL_STATE } from \"../global-state.js\";\nimport { normalizePaddingInsets } from \"./box-insets.js\";\nimport type { BoxStyle } from \"../style/types.js\";\nimport type { LayoutBox } from \"./types.js\";\n\n/** @internal A pushed allocation remains active through ordinary components. */\nexport function hasParentLayoutAllocation(): boolean {\n  return (GLOBAL_STATE.layoutStack?.length ?? 0) > 1;\n}\n\n/** @internal Inherited inline direction; roots default to LTR. */\nexport function getLayoutDirection(): \"ltr\" | \"rtl\" {\n  return GLOBAL_STATE.layoutStack?.at(-1)?.layoutDirection ?? \"ltr\";\n}\n\nexport function getLayoutBox(): Readonly<LayoutBox> {\n  const context = GLOBAL_STATE.layoutStack?.at(-1);\n  if (!context) {\n    throw new Error(\"No Pibbl layout context is available\");\n  }\n  return context.allocation;\n}\n\nexport function getPercentageBasis(): Readonly<LayoutBox> {\n  const context = GLOBAL_STATE.layoutStack?.at(-1);\n  if (!context) {\n    throw new Error(\"No Pibbl layout context is available\");\n  }\n  return context.percentageBasis;\n}\n\ninterface LogicalLayoutContext {\n  readonly x: number;\n  readonly y: number;\n  readonly containing: Readonly<LayoutBox>;\n}\nconst logicalContexts = new WeakMap<object, LogicalLayoutContext>();\nconst ROOT_LOGICAL_ORIGIN = Object.freeze({ x: 0, y: 0 });\n\n/** @internal Current accumulated layout origin, before Canvas presentation transforms. */\nexport function getLogicalLayoutOrigin(): Readonly<{ x: number; y: number }> {\n  const context = GLOBAL_STATE.layoutStack?.at(-1);\n  if (!context) throw new Error('No Pibbl layout context is available');\n  return logicalContexts.get(context) ?? ROOT_LOGICAL_ORIGIN;\n}\n\n/** The nearest positioned layout box, expressed before presentation transforms. */\nexport function getLogicalContainingBox(): Readonly<LayoutBox> {\n  const context = GLOBAL_STATE.layoutStack?.at(-1);\n  if (!context)\n    throw new Error(\"No Pibbl containing layout context is available\");\n  const logical = logicalContexts.get(context);\n  if (!logical) return context.allocation;\n  return {\n    x: logical.containing.x - logical.x,\n    y: logical.containing.y - logical.y,\n    width: logical.containing.width,\n    height: logical.containing.height,\n  };\n}\n\n/**\n * Resolves the positioned containing block in the current layout coordinates.\n * A positioned layout boundary owns its padding box; a static boundary stays\n * transparent and inherits the nearest positioned ancestor.\n *\n * @internal\n */\nexport function resolvePositionedContainingBox(\n  style: Readonly<BoxStyle & { readonly position?: string }>,\n  content: Readonly<LayoutBox>,\n  component: string,\n): Readonly<LayoutBox> | undefined {\n  if (style.position === \"static\") return undefined;\n  const padding = normalizePaddingInsets(style, {\n    component,\n    algorithm: \"containing block\",\n    constraints: {\n      minWidth: 0,\n      maxWidth: content.width,\n      minHeight: 0,\n      maxHeight: content.height,\n    },\n  });\n  return Object.freeze({\n    x: content.x - padding.left,\n    y: content.y - padding.top,\n    width: content.width + padding.left + padding.right,\n    height: content.height + padding.top + padding.bottom,\n  });\n}\n\n/**\n * Pushes one finite layout allocation and returns its exact restoration callback.\n *\n * @param box - Child allocation to expose during nested layout work.\n * @param options - Optional inherited direction and containing-block metadata.\n * @returns A callback that restores the prior layout context.\n *\n * @see {@link LayoutBox}\n */\nexport function pushLayoutBox(\n  box: Readonly<LayoutBox>,\n  options?: {\n    readonly layoutDirection?: \"ltr\" | \"rtl\";\n    readonly logicalOffset?: Readonly<{ x: number; y: number }>;\n    readonly containingBlock?: Readonly<LayoutBox>;\n  },\n): () => void {\n  const stack = GLOBAL_STATE.layoutStack;\n  if (!stack) {\n    throw new Error(\"No Pibbl layout context is available\");\n  }\n  const parent = stack.at(-1);\n  if (!parent) {\n    throw new Error(\"No Pibbl parent layout context is available\");\n  }\n  const context = {\n    allocation: box,\n    percentageBasis: parent.allocation,\n    layoutDirection:\n      options?.layoutDirection ?? parent.layoutDirection ?? \"ltr\",\n  };\n  const inherited = logicalContexts.get(parent);\n  const x = (inherited?.x ?? 0) + (options?.logicalOffset?.x ?? 0);\n  const y = (inherited?.y ?? 0) + (options?.logicalOffset?.y ?? 0);\n  const declared = options?.containingBlock;\n  logicalContexts.set(context, {\n    x,\n    y,\n    containing: declared\n      ? {\n          x: x + declared.x,\n          y: y + declared.y,\n          width: declared.width,\n          height: declared.height,\n        }\n      : (inherited?.containing ?? parent.allocation),\n  });\n  stack.push(context);\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    if (stack.at(-1) !== context) {\n      throw new Error(\"Pibbl layout context was restored out of order\");\n    }\n    stack.pop();\n  };\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/lib/layout/define-layout-component.d.ts

@@ -0,0 +1,23 @@
+import type { PibblComponent, PibblElement, PibblNodeInput } from '../element/types.js';
+import { type PreparedStyleInput } from '../style/resolve-dispatch.js';
+/**
+ * Defines pure reusable structure that a parent can inspect before allocation.
+ * The description returns one drawing or layout primitive root, optionally inside
+ * transparent fragments. Forward any authored style explicitly to that root.
+ * Signal reads are supported; hooks, Canvas/allocation reads, writes and resource
+ * creation are excluded. Descriptions are shared only within one transaction.
+ *
+ * @param describe - Pure synchronous description using authored readonly props.
+ * @returns A component for JSX or createElement, preserving normal type/key identity.
+ * @throws When called directly, or when its description has no single primitive root.
+ * @see {@link PibblComponent}
+ * @see {@link PibblNodeInput}
+ */
+export declare function defineLayoutComponent<P>(describe: (props: Readonly<P>) => PibblNodeInput): PibblComponent<P>;
+export declare function isLayoutComponent(type: Function): boolean;
+/** One prepared root per layout occurrence, never cached by mutable prop identity. */
+export declare function prepareLayoutComponent(element: PibblElement<any>, options?: {
+    receiverToken?: object;
+}): PibblElement<any>;
+/** Carries the parent's settled content size into the same prepared root. */
+export declare function placedLayoutComponentRoot(element: PibblElement<any>, style?: PreparedStyleInput): PibblElement<any>;

package/dist/lib/layout/define-layout-component.js

@@ -0,0 +1,84 @@
+import { clonePibblElement } from "../element/create-element.js";
+import { materializeContainerChildren } from "../element/children.js";
+import { getChildPrimitiveReceiverToken, getElementMetadata, setElementMetadata, getPrimitiveDefinition, getPrimitiveReceiverToken, setPrimitiveReceiverToken, isPlacementConsumed, setPlacementConsumed } from "../element/metadata.js";
+import { GLOBAL_STATE } from "../global-state.js";
+import { withHooksForbidden } from "../hooks/hook-slot.js";
+import { withSignalWriteForbidden } from "../signals/graph.js";
+import { adoptReceiverInputProvision, withReceiverInputProvision } from "../signals/input-provision.js";
+import { withIsolatedRenderState } from "./measure.js";
+import { setPreNormalizedStyle } from "../style/resolve-dispatch.js";
+const definitions = /* @__PURE__ */ new WeakMap();
+const transactions = /* @__PURE__ */ new WeakMap();
+function defineLayoutComponent(describe) {
+  if (typeof describe !== "function") throw new TypeError("A layout description must be a function.");
+  const component = function LayoutComponent() {
+    throw new Error("Mount layout components through JSX or createElement; do not call them directly.");
+  };
+  definitions.set(component, describe);
+  return component;
+}
+function isLayoutComponent(type) {
+  return definitions.has(type);
+}
+function prepareLayoutComponent(element, options) {
+  const describe = definitions.get(element.type);
+  if (!describe) throw new Error("The element has no structural layout description.");
+  const transaction = GLOBAL_STATE.renderTransaction;
+  const receiver = options?.receiverToken ?? getPrimitiveReceiverToken(element) ?? (GLOBAL_STATE.componentRefs?.element === element ? GLOBAL_STATE.componentRefs : element);
+  let prepared = transaction ? transactions.get(transaction) : void 0;
+  const cached = prepared?.get(receiver);
+  if (cached) return cached;
+  const root = withHooksForbidden(
+    "Hooks are forbidden in a layout description.",
+    () => withSignalWriteForbidden(
+      "Signal writes are forbidden in a layout description.",
+      () => withIsolatedRenderState(() => withReceiverInputProvision(transaction, receiver, () => {
+        const roots = materializeContainerChildren(describe(element.props), element);
+        if (roots.length !== 1 || !getPrimitiveDefinition(roots[0].type)) {
+          throw new Error("A layout description must return exactly one drawing or layout primitive root.");
+        }
+        const root2 = clonePibblElement(roots[0]);
+        setElementMetadata(root2, {
+          ...getElementMetadata(root2),
+          layoutDescriptionSource: getElementMetadata(roots[0])?.layoutDescriptionSource ?? roots[0]
+        });
+        return root2;
+      }))
+    )
+  );
+  const current = GLOBAL_STATE.componentRefs;
+  if (current && (getPrimitiveReceiverToken(current.element) ?? current) === receiver) {
+    adoptReceiverInputProvision(transaction, receiver);
+  }
+  setPrimitiveReceiverToken(root, getChildPrimitiveReceiverToken(transaction, receiver, 0));
+  if (transaction) {
+    if (!prepared) {
+      prepared = /* @__PURE__ */ new WeakMap();
+      transactions.set(transaction, prepared);
+    }
+    prepared.set(receiver, root);
+  }
+  return root;
+}
+function placedLayoutComponentRoot(element, style) {
+  const root = prepareLayoutComponent(element);
+  const slot = getElementMetadata(element)?.preparedLayoutSlot;
+  if (!style && !slot) return root;
+  const placed = clonePibblElement(root);
+  if (isPlacementConsumed(element)) setPlacementConsumed(placed);
+  if (style) setPreNormalizedStyle(placed, style.style, root, getPrimitiveReceiverToken(root), style.query);
+  const metadata = getElementMetadata(element);
+  if (slot || metadata?.absoluteContainingBlock) setElementMetadata(placed, {
+    ...getElementMetadata(placed),
+    ...slot ? { preparedLayoutSlot: slot } : void 0,
+    ...metadata?.absoluteContainingBlock ? { absoluteContainingBlock: metadata.absoluteContainingBlock } : void 0
+  });
+  return placed;
+}
+export {
+  defineLayoutComponent,
+  isLayoutComponent,
+  placedLayoutComponentRoot,
+  prepareLayoutComponent
+};
+//# sourceMappingURL=define-layout-component.js.map

package/dist/lib/layout/define-layout-component.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/layout/define-layout-component.ts"],
+  "sourcesContent": ["import type { PibblComponent, PibblElement, PibblNodeInput } from '../element/types.js';\nimport { clonePibblElement } from '../element/create-element.js';\nimport { materializeContainerChildren } from '../element/children.js';\nimport { getChildPrimitiveReceiverToken, getElementMetadata, setElementMetadata, getPrimitiveDefinition, getPrimitiveReceiverToken, setPrimitiveReceiverToken, isPlacementConsumed, setPlacementConsumed } from '../element/metadata.js';\nimport { GLOBAL_STATE } from '../global-state.js';\nimport { withHooksForbidden } from '../hooks/hook-slot.js';\nimport { withSignalWriteForbidden } from '../signals/graph.js';\nimport { adoptReceiverInputProvision, withReceiverInputProvision } from '../signals/input-provision.js';\nimport type { PibblRenderTransaction } from '../types.js';\nimport { withIsolatedRenderState } from './measure.js';\nimport { setPreNormalizedStyle, type PreparedStyleInput } from '../style/resolve-dispatch.js';\n\nconst definitions = new WeakMap<Function, (props: any) => PibblNodeInput>();\nconst transactions = new WeakMap<PibblRenderTransaction, WeakMap<object, PibblElement<any>>>();\n\n/**\n * Defines pure reusable structure that a parent can inspect before allocation.\n * The description returns one drawing or layout primitive root, optionally inside\n * transparent fragments. Forward any authored style explicitly to that root.\n * Signal reads are supported; hooks, Canvas/allocation reads, writes and resource\n * creation are excluded. Descriptions are shared only within one transaction.\n *\n * @param describe - Pure synchronous description using authored readonly props.\n * @returns A component for JSX or createElement, preserving normal type/key identity.\n * @throws When called directly, or when its description has no single primitive root.\n * @see {@link PibblComponent}\n * @see {@link PibblNodeInput}\n */\nexport function defineLayoutComponent<P>(\n  describe: (props: Readonly<P>) => PibblNodeInput,\n): PibblComponent<P> {\n  if (typeof describe !== 'function') throw new TypeError('A layout description must be a function.');\n  const component: PibblComponent<P> = function LayoutComponent() {\n    throw new Error('Mount layout components through JSX or createElement; do not call them directly.');\n  };\n  definitions.set(component, describe);\n  return component;\n}\n\nexport function isLayoutComponent(type: Function): boolean { return definitions.has(type); }\n\n/** One prepared root per layout occurrence, never cached by mutable prop identity. */\nexport function prepareLayoutComponent(\n  element: PibblElement<any>, options?: { receiverToken?: object },\n): PibblElement<any> {\n  const describe = definitions.get(element.type);\n  if (!describe) throw new Error('The element has no structural layout description.');\n  const transaction = GLOBAL_STATE.renderTransaction;\n  const receiver = options?.receiverToken ?? getPrimitiveReceiverToken(element) ??\n    (GLOBAL_STATE.componentRefs?.element === element ? GLOBAL_STATE.componentRefs : element);\n  let prepared = transaction ? transactions.get(transaction) : undefined;\n  const cached = prepared?.get(receiver);\n  if (cached) return cached;\n  const root = withHooksForbidden('Hooks are forbidden in a layout description.', () =>\n    withSignalWriteForbidden('Signal writes are forbidden in a layout description.', () =>\n      withIsolatedRenderState(() => withReceiverInputProvision(transaction, receiver, () => {\n        const roots = materializeContainerChildren(describe(element.props), element);\n        if (roots.length !== 1 || !getPrimitiveDefinition(roots[0].type)) {\n          throw new Error('A layout description must return exactly one drawing or layout primitive root.');\n        }\n        const root = clonePibblElement(roots[0]);\n        setElementMetadata(root, {\n          ...getElementMetadata(root),\n          layoutDescriptionSource: getElementMetadata(roots[0])?.layoutDescriptionSource ?? roots[0],\n        });\n        return root;\n      })),\n    ),\n  );\n  const current = GLOBAL_STATE.componentRefs;\n  if (current && (getPrimitiveReceiverToken(current.element) ?? current) === receiver) {\n    adoptReceiverInputProvision(transaction, receiver);\n  }\n  setPrimitiveReceiverToken(root, getChildPrimitiveReceiverToken(transaction, receiver, 0));\n  if (transaction) {\n    if (!prepared) { prepared = new WeakMap(); transactions.set(transaction, prepared); }\n    prepared.set(receiver, root);\n  }\n  return root;\n}\n\n/** Carries the parent's settled content size into the same prepared root. */\nexport function placedLayoutComponentRoot(element: PibblElement<any>, style?: PreparedStyleInput): PibblElement<any> {\n  const root = prepareLayoutComponent(element);\n  const slot = getElementMetadata(element)?.preparedLayoutSlot;\n  if (!style && !slot) return root;\n  const placed = clonePibblElement(root);\n  // The description is transparent: its one actual root consumes the already\n  // allocated placement, including explicit static/relative positioning, once.\n  if (isPlacementConsumed(element)) setPlacementConsumed(placed);\n  if (style) setPreNormalizedStyle(placed, style.style, root, getPrimitiveReceiverToken(root), style.query);\n  const metadata = getElementMetadata(element);\n  if (slot || metadata?.absoluteContainingBlock) setElementMetadata(placed, {\n    ...getElementMetadata(placed),\n    ...(slot ? { preparedLayoutSlot: slot } : undefined),\n    ...(metadata?.absoluteContainingBlock ? { absoluteContainingBlock: metadata.absoluteContainingBlock } : undefined),\n  });\n  return placed;\n}\n"],
+  "mappings": "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",
+  "names": ["root"]
+}

package/dist/lib/layout/flex-allocation-cache.d.ts

@@ -0,0 +1,42 @@
+import { FLEX_BASELINE_GROUP, FLEX_LAST_BASELINE } from './flex-baseline-mode.js';
+import type { PibblElement } from '../element/types.js';
+import type { AllocationInputState } from './allocation-revision.js';
+import type { LayoutBox } from './types.js';
+export interface AllocationSettings {
+    [FLEX_BASELINE_GROUP]?: boolean;
+    [FLEX_LAST_BASELINE]?: boolean;
+    layoutDirection: 'ltr' | 'rtl';
+    flexDirection: string;
+    flexWrap: string;
+    justifyContent: string;
+    alignItems: string;
+    alignContent: string;
+    rowGap: number;
+    columnGap: number;
+}
+export interface CachedFlexPlacement {
+    readonly box: Readonly<LayoutBox>;
+    /** Physical outer y before relative paint translation. */
+    readonly layoutY: number;
+    readonly usedWidth: number;
+    readonly usedHeight: number;
+}
+type SignalVersionNode = Readonly<{
+    version: number;
+}>;
+/** One scalar snapshot; its input identity is weak and never owns descriptors. */
+export declare class FlexAllocationCache {
+    private input;
+    private state;
+    private dependencies;
+    private width;
+    private height;
+    private settings;
+    private placements;
+    read(input: unknown, state: AllocationInputState, box: Readonly<LayoutBox>, settings: AllocationSettings): readonly CachedFlexPlacement[] | undefined;
+    store(input: object, state: AllocationInputState, box: Readonly<LayoutBox>, settings: AllocationSettings, placements: readonly CachedFlexPlacement[], dependencies?: readonly SignalVersionNode[]): void;
+}
+/** Captures only declared frozen metric signals; opaque components never participate. */
+export declare function frozenFlexMetricDependencies(input: unknown): readonly SignalVersionNode[] | undefined;
+export declare function frozenFlexInputs(input: unknown, dependencies?: SignalVersionNode[]): input is readonly PibblElement<any>[];
+export {};

package/dist/lib/layout/flex-baseline-mode.d.ts

@@ -0,0 +1,2 @@
+export declare const FLEX_BASELINE_GROUP: unique symbol;
+export declare const FLEX_LAST_BASELINE: unique symbol;

package/dist/lib/layout/flex-baseline-mode.js

@@ -0,0 +1,7 @@
+const FLEX_BASELINE_GROUP = /* @__PURE__ */ Symbol("pibbl.flex-baseline-group");
+const FLEX_LAST_BASELINE = /* @__PURE__ */ Symbol("pibbl.flex-last-baseline");
+export {
+  FLEX_BASELINE_GROUP,
+  FLEX_LAST_BASELINE
+};
+//# sourceMappingURL=flex-baseline-mode.js.map