@pibbl/core 0.0.1

package/dist/lib/components/wedge.js

@@ -0,0 +1,93 @@
+import { definePrimitive } from "../define-primitive.js";
+import {
+  resolveLocalOffset,
+  stripLayoutParticipation
+} from "../style/resolve-built-in.js";
+import { registerOpaqueStyleProperties } from "../style/resolve-dispatch.js";
+import { wedgeBounds } from "./arc-geometry.js";
+import {
+  createWedgePath,
+  resolveCircularSweep
+} from "../geometry/circular-sweep.js";
+import { renderPath } from "./path.js";
+import {
+  circularPercentageBasis,
+  resolveFiniteShapeNumber,
+  resolveNonnegativeShapeLength
+} from "./shape-style.js";
+function renderWedge(props, style, ctx) {
+  const {
+    cx,
+    cy,
+    radius,
+    startAngle,
+    endAngle,
+    counterclockwise,
+    fill,
+    stroke,
+    strokeWidth,
+    opacity,
+    cursor,
+    lineInteractionWidth
+  } = style;
+  const sweep = resolveCircularSweep(startAngle, endAngle, counterclockwise);
+  const path = createWedgePath({
+    cx,
+    cy,
+    radius,
+    startAngle,
+    endAngle,
+    counterclockwise
+  });
+  return renderPath(
+    {
+      ...props,
+      keyboardNavigationBounds: props.keyboardNavigationBounds ?? wedgeBounds(cx, cy, radius, sweep)
+    },
+    {
+      d: path,
+      fill,
+      stroke,
+      strokeWidth,
+      opacity,
+      cursor,
+      lineInteractionWidth
+    },
+    ctx
+  );
+}
+const Wedge = definePrimitive(renderWedge, {
+  resolveStyle: (style, context) => ({
+    ...stripLayoutParticipation(style),
+    cx: resolveLocalOffset(
+      style.cx,
+      context.percentageBasis.width,
+      "cx",
+      context
+    ),
+    cy: resolveLocalOffset(
+      style.cy,
+      context.percentageBasis.height,
+      "cy",
+      context
+    ),
+    radius: resolveNonnegativeShapeLength(
+      style.radius,
+      circularPercentageBasis(context),
+      "radius",
+      context
+    ),
+    startAngle: resolveFiniteShapeNumber(
+      style.startAngle,
+      "startAngle",
+      context
+    ),
+    endAngle: resolveFiniteShapeNumber(style.endAngle, "endAngle", context),
+    counterclockwise: style.counterclockwise ?? false
+  })
+});
+registerOpaqueStyleProperties(Wedge, ["fill", "stroke", "cursor"]);
+export {
+  Wedge
+};
+//# sourceMappingURL=wedge.js.map

package/dist/lib/components/wedge.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/components/wedge.ts"],
+  "sourcesContent": ["import { definePrimitive } from \"../define-primitive.js\";\nimport type {\n  PibblEventFocusOptions,\n  PibblEventHandlers,\n  PibblEventParticipationOptions,\n} from \"../events/types.js\";\nimport {\n  resolveLocalOffset,\n  stripLayoutParticipation,\n} from \"../style/resolve-built-in.js\";\nimport { registerOpaqueStyleProperties } from \"../style/resolve-dispatch.js\";\nimport type {\n  BoxStyle,\n  CursorStyle,\n  LayoutItemStyle,\n  Length,\n  PaintStyle,\n  ResolvedDrawingStyle,\n} from \"../style/types.js\";\nimport type { RenderingContext2D, SystemStyle } from \"../types.js\";\nimport type { PibblPhysics2DPropExtension } from \"../types.js\";\nimport { wedgeBounds } from \"./arc-geometry.js\";\nimport {\n  createWedgePath,\n  resolveCircularSweep,\n} from \"../geometry/circular-sweep.js\";\nimport { renderPath } from \"./path.js\";\nimport {\n  circularPercentageBasis,\n  resolveFiniteShapeNumber,\n  resolveNonnegativeShapeLength,\n} from \"./shape-style.js\";\n\n/**\n * Authored inputs for Wedge, including the declared data and presentation options.\n *\n * @see {@link PibblEventHandlers}\n * @see {@link PibblEventParticipationOptions}\n * @see {@link PibblPhysics2DPropExtension}\n * @see {@link Wedge}\n */\nexport interface WedgeProps extends PibblEventHandlers, PibblEventFocusOptions, PibblEventParticipationOptions, PibblPhysics2DPropExtension {}\n\n/**\n * Supported geometry and presentation properties for Wedge.\n *\n * @see {@link SystemStyle}\n * @see {@link PaintStyle}\n * @see {@link CursorStyle}\n * @see {@link BoxStyle}\n * @see {@link LayoutItemStyle}\n * @see {@link Length}\n * @see {@link Wedge}\n */\nexport interface WedgeStyle\n  extends SystemStyle, PaintStyle, CursorStyle, BoxStyle, LayoutItemStyle {\n  /** Radius in the coordinate system of this geometry or effect. See {@link Length}. */\n  radius: Exclude<Length, \"auto\">;\n  /** Angle at which the arc or slice begins. See {@link WedgeStyle}. */\n  startAngle: number;\n  /** Angle at which the arc or slice ends. See {@link WedgeStyle}. */\n  endAngle: number;\n  /** Horizontal coordinate of the center. See {@link Length}. */\n  cx?: Exclude<Length, \"auto\">;\n  /** Vertical coordinate of the center. See {@link Length}. */\n  cy?: Exclude<Length, \"auto\">;\n  /** Whether the arc follows the counterclockwise direction. See {@link WedgeStyle}. */\n  counterclockwise?: boolean;\n  /**\n   * Width used for line hit testing independently of the visible stroke width. See\n   * {@link WedgeStyle}.\n   */\n  lineInteractionWidth?: number;\n}\n\ntype ResolvedWedgeStyle = ResolvedDrawingStyle<WedgeStyle> & {\n  radius: number;\n  startAngle: number;\n  endAngle: number;\n  cx: number;\n  cy: number;\n  counterclockwise: boolean;\n};\n\nfunction renderWedge(\n  props: WedgeProps,\n  style: Readonly<ResolvedWedgeStyle>,\n  ctx: RenderingContext2D,\n) {\n  const {\n    cx,\n    cy,\n    radius,\n    startAngle,\n    endAngle,\n    counterclockwise,\n    fill,\n    stroke,\n    strokeWidth,\n    opacity,\n    cursor,\n    lineInteractionWidth,\n  } = style;\n  const sweep = resolveCircularSweep(startAngle, endAngle, counterclockwise);\n  const path = createWedgePath({\n    cx,\n    cy,\n    radius,\n    startAngle,\n    endAngle,\n    counterclockwise,\n  });\n\n  return renderPath(\n    {\n      ...props,\n      keyboardNavigationBounds:\n        props.keyboardNavigationBounds ?? wedgeBounds(cx, cy, radius, sweep),\n    },\n    {\n      d: path,\n      fill,\n      stroke,\n      strokeWidth,\n      opacity,\n      cursor,\n      lineInteractionWidth,\n    },\n    ctx,\n  );\n}\n\n/**\n * Describes a center-closed circular wedge primitive for JSX or createElement authoring.\n *\n * @param props - Authored component inputs, supplied through JSX or createElement. See the linked\n * props and style types.\n * @throws When called directly; Pibbl mounts this component through JSX or createElement.\n *\n * @see {@link WedgeProps}\n * @see {@link WedgeStyle}\n */\nexport const Wedge = definePrimitive<\n  WedgeProps,\n  WedgeStyle,\n  WedgeStyle,\n  ResolvedWedgeStyle\n>(renderWedge, {\n  resolveStyle: (style, context) =>\n    ({\n      ...stripLayoutParticipation(style),\n      cx: resolveLocalOffset(\n        style.cx,\n        context.percentageBasis.width,\n        \"cx\",\n        context,\n      ),\n      cy: resolveLocalOffset(\n        style.cy,\n        context.percentageBasis.height,\n        \"cy\",\n        context,\n      ),\n      radius: resolveNonnegativeShapeLength(\n        style.radius,\n        circularPercentageBasis(context),\n        \"radius\",\n        context,\n      ),\n      startAngle: resolveFiniteShapeNumber(\n        style.startAngle,\n        \"startAngle\",\n        context,\n      ),\n      endAngle: resolveFiniteShapeNumber(style.endAngle, \"endAngle\", context),\n      counterclockwise: style.counterclockwise ?? false,\n    }) as ResolvedWedgeStyle,\n});\nregisterOpaqueStyleProperties(Wedge, [\"fill\", \"stroke\", \"cursor\"]);\n"],
+  "mappings": "AAAA,SAAS,uBAAuB;AAMhC;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP,SAAS,qCAAqC;AAW9C,SAAS,mBAAmB;AAC5B;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP,SAAS,kBAAkB;AAC3B;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAqDP,SAAS,YACP,OACA,OACA,KACA;AACA,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,IAAI;AACJ,QAAM,QAAQ,qBAAqB,YAAY,UAAU,gBAAgB;AACzE,QAAM,OAAO,gBAAgB;AAAA,IAC3B;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAED,SAAO;AAAA,IACL;AAAA,MACE,GAAG;AAAA,MACH,0BACE,MAAM,4BAA4B,YAAY,IAAI,IAAI,QAAQ,KAAK;AAAA,IACvE;AAAA,IACA;AAAA,MACE,GAAG;AAAA,MACH;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA;AAAA,EACF;AACF;AAYO,MAAM,QAAQ,gBAKnB,aAAa;AAAA,EACb,cAAc,CAAC,OAAO,aACnB;AAAA,IACC,GAAG,yBAAyB,KAAK;AAAA,IACjC,IAAI;AAAA,MACF,MAAM;AAAA,MACN,QAAQ,gBAAgB;AAAA,MACxB;AAAA,MACA;AAAA,IACF;AAAA,IACA,IAAI;AAAA,MACF,MAAM;AAAA,MACN,QAAQ,gBAAgB;AAAA,MACxB;AAAA,MACA;AAAA,IACF;AAAA,IACA,QAAQ;AAAA,MACN,MAAM;AAAA,MACN,wBAAwB,OAAO;AAAA,MAC/B;AAAA,MACA;AAAA,IACF;AAAA,IACA,YAAY;AAAA,MACV,MAAM;AAAA,MACN;AAAA,MACA;AAAA,IACF;AAAA,IACA,UAAU,yBAAyB,MAAM,UAAU,YAAY,OAAO;AAAA,IACtE,kBAAkB,MAAM,oBAAoB;AAAA,EAC9C;AACJ,CAAC;AACD,8BAA8B,OAAO,CAAC,QAAQ,UAAU,QAAQ,CAAC;",
+  "names": []
+}

package/dist/lib/define-primitive.d.ts

@@ -0,0 +1,82 @@
+import type { PibblBackendPrimitiveProgram, PibblBackendToken } from './backend/types.js';
+import type { PibblPrimitiveComponent, PreservedSignalPropKey, PrimitiveCapabilities, PrimitiveInput, PrimitiveProgramProps, PrimitiveRender, SystemStyle } from './types.js';
+type DeclaresWhen<S> = S extends unknown ? 'when' extends keyof S ? true : false : never;
+type PrimitiveStyleGuard<S, N, R> = true extends DeclaresWhen<S> | DeclaresWhen<N> | DeclaresWhen<R> ? {
+    readonly 'Pibbl: style.when is framework-owned; remove when from the primitive style type': never;
+} : unknown;
+type AllocationValue = `${number}%` | 'auto';
+type DeclaredStyleValue<S> = S extends unknown ? S[Exclude<keyof S, 'custom'>] : never;
+type RequiresResolver<S> = [
+    Extract<DeclaredStyleValue<S>, AllocationValue>
+] extends [never] ? false : true;
+type PrimitiveCapabilitiesInput<P, S extends SystemStyle, N extends SystemStyle, R extends SystemStyle> = Readonly<PrimitiveCapabilities<P, S, N, R>> & PrimitiveStyleGuard<S, N, R> & ([
+    PreservedSignalPropKey<P>
+] extends [never] ? object : {
+    readonly preserveSignalProps: readonly [
+        PreservedSignalPropKey<P>,
+        ...PreservedSignalPropKey<P>[]
+    ];
+});
+type CapabilityArguments<P, S extends SystemStyle, N extends SystemStyle, R extends SystemStyle> = RequiresResolver<R> extends true ? [capabilities: never] : RequiresResolver<S> extends true ? [
+    capabilities: PrimitiveCapabilitiesInput<P, S, N, R> & {
+        resolveStyle: NonNullable<PrimitiveCapabilities<P, S, N, R>['resolveStyle']>;
+    }
+] : [PreservedSignalPropKey<P>] extends [never] ? [
+    capabilities?: PrimitiveCapabilitiesInput<P, S, N, R>
+] : [capabilities: PrimitiveCapabilitiesInput<P, S, N, R>];
+/**
+ * Defines a platform component with private style and measurement behavior.
+ *
+ * @param render - Synchronous primitive renderer receiving props, resolved style, and Canvas
+ * context. See {@link PrimitiveRender} , {@link PrimitiveStyleGuard} , {@link PrimitiveInput} .
+ * @param capabilityArguments - Style normalization, resolution, and measurement capabilities
+ * required by the primitive. See {@link CapabilityArguments} .
+ * @returns A primitive component usable with JSX or createElement. See
+ * {@link PibblPrimitiveComponent} , {@link PrimitiveProgramProps} , {@link PrimitiveInput} .
+ *
+ * @see {@link PrimitiveRender}
+ * @see {@link PrimitiveInput}
+ * @see {@link PibblPrimitiveComponent}
+ * @see {@link PrimitiveProgramProps}
+ * @see {@link SystemStyle}
+ */
+export declare function definePrimitive<P = Record<string, never>, S extends SystemStyle = SystemStyle, N extends SystemStyle = S, R extends SystemStyle = N>(render: PrimitiveRender<P, R> & PrimitiveStyleGuard<S, N, R> & (PrimitiveInput<P, S> extends never ? never : unknown), ...capabilityArguments: CapabilityArguments<P, S, N, R>): PibblPrimitiveComponent<PrimitiveProgramProps<P>, PrimitiveInput<P, S>>;
+/**
+ * Defines a primitive owned by one official Pibbl rendering backend.
+ *
+ * @param backend - Identity of the backend that can execute this primitive. See
+ * {@link PibblBackendToken} .
+ * @param program - Synchronous program using the active backend environment. See
+ * {@link PibblBackendPrimitiveProgram} , {@link PrimitiveStyleGuard} , {@link PrimitiveInput} .
+ * @param capabilityArguments - Style and measurement capabilities for the primitive. See
+ * {@link CapabilityArguments} .
+ * @returns A primitive component bound to the specified backend. See {@link PibblPrimitiveComponent}
+ * , {@link PrimitiveProgramProps} , {@link PrimitiveInput} .
+ *
+ * @see {@link PibblBackendToken}
+ * @see {@link PibblBackendPrimitiveProgram}
+ * @see {@link PrimitiveInput}
+ * @see {@link PibblPrimitiveComponent}
+ * @see {@link PrimitiveProgramProps}
+ * @see {@link SystemStyle}
+ */
+export declare function defineBackendPrimitive<P = Record<string, never>, S extends SystemStyle = SystemStyle, N extends SystemStyle = S, R extends SystemStyle = N, E = unknown>(backend: PibblBackendToken, program: PibblBackendPrimitiveProgram<P, R, E> & PrimitiveStyleGuard<S, N, R> & (PrimitiveInput<P, S> extends never ? never : unknown), ...capabilityArguments: CapabilityArguments<P, S, N, R>): PibblPrimitiveComponent<PrimitiveProgramProps<P>, PrimitiveInput<P, S>>;
+/**
+ * Derives a new official-package primitive identity with the source behavior.
+ *
+ * @param source - Primitive whose rendering and capabilities are reused.
+ * @returns A derived primitive with its own component identity.
+ *
+ * @see {@link PibblPrimitiveComponent}
+ */
+export declare function derivePrimitive<T extends PibblPrimitiveComponent<any, any>>(source: T): T;
+/**
+ * Runs one official-package primitive resolver without render side-effect authority.
+ *
+ * @param callback - Synchronous resolver to evaluate with hooks and signal writes forbidden.
+ * @returns The resolver's return value.
+ *
+ * @see {@link PrimitiveCapabilities}
+ */
+export declare function pibblInternalRunPurePrimitiveResolver<T>(callback: () => T): T;
+export {};

package/dist/lib/define-primitive.js

@@ -0,0 +1,85 @@
+import {
+  derivePrimitiveMetadata,
+  getPrimitiveDefinition,
+  setPrimitiveDefinition
+} from "./element/metadata.js";
+import {
+  CANVAS_2D_BACKEND
+} from "./backend/canvas-2d-backend.js";
+import { GLOBAL_STATE } from "./global-state.js";
+import { withSignalWriteForbidden } from "./signals/graph.js";
+function definePrimitive(render, ...capabilityArguments) {
+  return defineBackendPrimitive(
+    CANVAS_2D_BACKEND.token,
+    render,
+    ...capabilityArguments
+  );
+}
+function defineBackendPrimitive(backend, program, ...capabilityArguments) {
+  const componentName = primitiveComponentName(program.name);
+  const component = function PibblPrimitiveComponent() {
+    throw new Error(
+      `${componentName} is a Pibbl component and was invoked outside the Pibbl renderer.
+Use <${componentName} ... /> in a Pibbl JSX file or createElement(${componentName}, props).`
+    );
+  };
+  Object.defineProperty(component, "name", {
+    configurable: true,
+    value: componentName
+  });
+  const capabilities = capabilityArguments[0] ?? {};
+  setPrimitiveDefinition(component, {
+    backend,
+    program,
+    preserveSignalProps: capabilities.preserveSignalProps,
+    childInput: capabilities.childInput,
+    normalizeStyle: capabilities.normalizeStyle,
+    resolveStyle: capabilities.resolveStyle,
+    measure: capabilities.measure
+  });
+  return component;
+}
+function derivePrimitive(source) {
+  if (!getPrimitiveDefinition(source)) {
+    throw new TypeError("Can only derive a Pibbl primitive component.");
+  }
+  const componentName = source.name || "Anonymous";
+  const derived = function PibblPrimitiveComponent() {
+    throw new Error(
+      `${componentName} is a Pibbl component and was invoked outside the Pibbl renderer.
+Use <${componentName} ... /> in a Pibbl JSX file or createElement(${componentName}, props).`
+    );
+  };
+  Object.defineProperty(derived, "name", {
+    configurable: true,
+    value: componentName
+  });
+  derivePrimitiveMetadata(source, derived);
+  return derived;
+}
+function pibblInternalRunPurePrimitiveResolver(callback) {
+  const previousComponentRefs = GLOBAL_STATE.componentRefs;
+  const previousComponentHookIndex = GLOBAL_STATE.componentHookIndex;
+  const previousComponentIsMounting = GLOBAL_STATE.componentIsMounting;
+  GLOBAL_STATE.componentRefs = void 0;
+  GLOBAL_STATE.componentHookIndex = 0;
+  GLOBAL_STATE.componentIsMounting = false;
+  try {
+    return withSignalWriteForbidden("Pibbl pure primitive resolver", callback);
+  } finally {
+    GLOBAL_STATE.componentRefs = previousComponentRefs;
+    GLOBAL_STATE.componentHookIndex = previousComponentHookIndex;
+    GLOBAL_STATE.componentIsMounting = previousComponentIsMounting;
+  }
+}
+function primitiveComponentName(renderName) {
+  if (/^render[A-Z]/.test(renderName)) return renderName.slice("render".length);
+  return renderName || "Anonymous";
+}
+export {
+  defineBackendPrimitive,
+  definePrimitive,
+  derivePrimitive,
+  pibblInternalRunPurePrimitiveResolver
+};
+//# sourceMappingURL=define-primitive.js.map

package/dist/lib/define-primitive.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/define-primitive.ts"],
+  "sourcesContent": ["import {\n  derivePrimitiveMetadata,\n  getPrimitiveDefinition,\n  setPrimitiveDefinition,\n} from './element/metadata.js';\nimport {\n  CANVAS_2D_BACKEND,\n} from './backend/canvas-2d-backend.js';\nimport type {\n  PibblBackendPrimitiveProgram,\n  PibblBackendToken,\n} from './backend/types.js';\nimport type {\n  PibblPrimitiveComponent,\n  PreservedSignalPropKey,\n  PrimitiveCapabilities,\n  PrimitiveInput,\n  PrimitiveProgramProps,\n  PrimitiveRender,\n  RenderingContext2D,\n  SystemStyle,\n} from './types.js';\nimport { GLOBAL_STATE } from './global-state.js';\nimport { withSignalWriteForbidden } from './signals/graph.js';\n\ntype DeclaresWhen<S> = S extends unknown ? 'when' extends keyof S ? true : false : never;\ntype PrimitiveStyleGuard<S, N, R> = true extends DeclaresWhen<S> | DeclaresWhen<N> | DeclaresWhen<R> ? {\n  readonly 'Pibbl: style.when is framework-owned; remove when from the primitive style type': never;\n} : unknown;\n\ntype AllocationValue = `${number}%` | 'auto';\ntype DeclaredStyleValue<S> = S extends unknown\n  ? S[Exclude<keyof S, 'custom'>]\n  : never;\ntype RequiresResolver<S> = [\n  Extract<DeclaredStyleValue<S>, AllocationValue>,\n] extends [never] ? false : true;\ntype PrimitiveCapabilitiesInput<\n  P,\n  S extends SystemStyle,\n  N extends SystemStyle,\n  R extends SystemStyle,\n> = Readonly<PrimitiveCapabilities<P, S, N, R>> & PrimitiveStyleGuard<S, N, R> & (\n  [PreservedSignalPropKey<P>] extends [never] ? object : {\n    readonly preserveSignalProps: readonly [\n      PreservedSignalPropKey<P>,\n      ...PreservedSignalPropKey<P>[],\n    ];\n  }\n);\ntype CapabilityArguments<\n  P,\n  S extends SystemStyle,\n  N extends SystemStyle,\n  R extends SystemStyle,\n> = RequiresResolver<R> extends true ? [capabilities: never] :\n  RequiresResolver<S> extends true ? [\n    capabilities: PrimitiveCapabilitiesInput<P, S, N, R> & {\n      resolveStyle: NonNullable<\n        PrimitiveCapabilities<P, S, N, R>['resolveStyle']\n      >;\n    },\n  ] : [PreservedSignalPropKey<P>] extends [never] ? [\n    capabilities?: PrimitiveCapabilitiesInput<P, S, N, R>,\n  ] : [capabilities: PrimitiveCapabilitiesInput<P, S, N, R>];\n\n/**\n * Defines a platform component with private style and measurement behavior.\n *\n * @param render - Synchronous primitive renderer receiving props, resolved style, and Canvas\n * context. See {@link PrimitiveRender} , {@link PrimitiveStyleGuard} , {@link PrimitiveInput} .\n * @param capabilityArguments - Style normalization, resolution, and measurement capabilities\n * required by the primitive. See {@link CapabilityArguments} .\n * @returns A primitive component usable with JSX or createElement. See\n * {@link PibblPrimitiveComponent} , {@link PrimitiveProgramProps} , {@link PrimitiveInput} .\n *\n * @see {@link PrimitiveRender}\n * @see {@link PrimitiveInput}\n * @see {@link PibblPrimitiveComponent}\n * @see {@link PrimitiveProgramProps}\n * @see {@link SystemStyle}\n */\nexport function definePrimitive<\n  P = Record<string, never>,\n  S extends SystemStyle = SystemStyle,\n  N extends SystemStyle = S,\n  R extends SystemStyle = N,\n>(\n  render: PrimitiveRender<P, R> & PrimitiveStyleGuard<S, N, R> & (\n    PrimitiveInput<P, S> extends never ? never : unknown\n  ),\n  ...capabilityArguments: CapabilityArguments<P, S, N, R>\n): PibblPrimitiveComponent<PrimitiveProgramProps<P>, PrimitiveInput<P, S>> {\n  return defineBackendPrimitive<P, S, N, R, RenderingContext2D>(\n    CANVAS_2D_BACKEND.token,\n    render,\n    ...capabilityArguments,\n  );\n}\n\n/**\n * Defines a primitive owned by one official Pibbl rendering backend.\n *\n * @param backend - Identity of the backend that can execute this primitive. See\n * {@link PibblBackendToken} .\n * @param program - Synchronous program using the active backend environment. See\n * {@link PibblBackendPrimitiveProgram} , {@link PrimitiveStyleGuard} , {@link PrimitiveInput} .\n * @param capabilityArguments - Style and measurement capabilities for the primitive. See\n * {@link CapabilityArguments} .\n * @returns A primitive component bound to the specified backend. See {@link PibblPrimitiveComponent}\n * , {@link PrimitiveProgramProps} , {@link PrimitiveInput} .\n *\n * @see {@link PibblBackendToken}\n * @see {@link PibblBackendPrimitiveProgram}\n * @see {@link PrimitiveInput}\n * @see {@link PibblPrimitiveComponent}\n * @see {@link PrimitiveProgramProps}\n * @see {@link SystemStyle}\n */\nexport function defineBackendPrimitive<\n  P = Record<string, never>,\n  S extends SystemStyle = SystemStyle,\n  N extends SystemStyle = S,\n  R extends SystemStyle = N,\n  E = unknown,\n>(\n  backend: PibblBackendToken,\n  program: PibblBackendPrimitiveProgram<P, R, E> & PrimitiveStyleGuard<S, N, R> & (\n    PrimitiveInput<P, S> extends never ? never : unknown\n  ),\n  ...capabilityArguments: CapabilityArguments<P, S, N, R>\n): PibblPrimitiveComponent<PrimitiveProgramProps<P>, PrimitiveInput<P, S>> {\n  const componentName = primitiveComponentName(program.name);\n  const component = function PibblPrimitiveComponent(): never {\n    throw new Error(\n      `${componentName} is a Pibbl component and was invoked outside the Pibbl ` +\n      'renderer.\\n' +\n      `Use <${componentName} ... /> in a Pibbl JSX file or ` +\n      `createElement(${componentName}, props).`,\n    );\n  } as unknown as PibblPrimitiveComponent<\n    PrimitiveProgramProps<P>,\n    PrimitiveInput<P, S>\n  >;\n  Object.defineProperty(component, 'name', {\n    configurable: true,\n    value: componentName,\n  });\n\n  const capabilities = (capabilityArguments[0] ?? {}) as Readonly<\n    PrimitiveCapabilities<P, S, N, R>\n  >;\n  setPrimitiveDefinition(component, {\n    backend,\n    program,\n    preserveSignalProps: capabilities.preserveSignalProps,\n    childInput: capabilities.childInput,\n    normalizeStyle: capabilities.normalizeStyle,\n    resolveStyle: capabilities.resolveStyle,\n    measure: capabilities.measure,\n  });\n  return component;\n}\n\n/**\n * Derives a new official-package primitive identity with the source behavior.\n *\n * @param source - Primitive whose rendering and capabilities are reused.\n * @returns A derived primitive with its own component identity.\n *\n * @see {@link PibblPrimitiveComponent}\n */\nexport function derivePrimitive<T extends PibblPrimitiveComponent<any, any>>(\n  source: T,\n): T {\n  if (!getPrimitiveDefinition(source)) {\n    throw new TypeError('Can only derive a Pibbl primitive component.');\n  }\n  const componentName = source.name || 'Anonymous';\n  const derived = function PibblPrimitiveComponent(): never {\n    throw new Error(\n      `${componentName} is a Pibbl component and was invoked outside the Pibbl ` +\n      'renderer.\\n' +\n      `Use <${componentName} ... /> in a Pibbl JSX file or ` +\n      `createElement(${componentName}, props).`,\n    );\n  } as unknown as T;\n  Object.defineProperty(derived, 'name', {\n    configurable: true,\n    value: componentName,\n  });\n  derivePrimitiveMetadata(source, derived);\n  return derived;\n}\n\n/**\n * Runs one official-package primitive resolver without render side-effect authority.\n *\n * @param callback - Synchronous resolver to evaluate with hooks and signal writes forbidden.\n * @returns The resolver's return value.\n *\n * @see {@link PrimitiveCapabilities}\n */\nexport function pibblInternalRunPurePrimitiveResolver<T>(callback: () => T): T {\n  const previousComponentRefs = GLOBAL_STATE.componentRefs;\n  const previousComponentHookIndex = GLOBAL_STATE.componentHookIndex;\n  const previousComponentIsMounting = GLOBAL_STATE.componentIsMounting;\n  GLOBAL_STATE.componentRefs = undefined;\n  GLOBAL_STATE.componentHookIndex = 0;\n  GLOBAL_STATE.componentIsMounting = false;\n  try {\n    return withSignalWriteForbidden('Pibbl pure primitive resolver', callback);\n  } finally {\n    GLOBAL_STATE.componentRefs = previousComponentRefs;\n    GLOBAL_STATE.componentHookIndex = previousComponentHookIndex;\n    GLOBAL_STATE.componentIsMounting = previousComponentIsMounting;\n  }\n}\n\nfunction primitiveComponentName(renderName: string): string {\n  if (/^render[A-Z]/.test(renderName)) return renderName.slice('render'.length);\n  return renderName || 'Anonymous';\n}\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,OACK;AAeP,SAAS,oBAAoB;AAC7B,SAAS,gCAAgC;AA2DlC,SAAS,gBAMd,WAGG,qBACsE;AACzE,SAAO;AAAA,IACL,kBAAkB;AAAA,IAClB;AAAA,IACA,GAAG;AAAA,EACL;AACF;AAqBO,SAAS,uBAOd,SACA,YAGG,qBACsE;AACzE,QAAM,gBAAgB,uBAAuB,QAAQ,IAAI;AACzD,QAAM,YAAY,SAAS,0BAAiC;AAC1D,UAAM,IAAI;AAAA,MACR,GAAG,aAAa;AAAA,OAER,aAAa,gDACJ,aAAa;AAAA,IAChC;AAAA,EACF;AAIA,SAAO,eAAe,WAAW,QAAQ;AAAA,IACvC,cAAc;AAAA,IACd,OAAO;AAAA,EACT,CAAC;AAED,QAAM,eAAgB,oBAAoB,CAAC,KAAK,CAAC;AAGjD,yBAAuB,WAAW;AAAA,IAChC;AAAA,IACA;AAAA,IACA,qBAAqB,aAAa;AAAA,IAClC,YAAY,aAAa;AAAA,IACzB,gBAAgB,aAAa;AAAA,IAC7B,cAAc,aAAa;AAAA,IAC3B,SAAS,aAAa;AAAA,EACxB,CAAC;AACD,SAAO;AACT;AAUO,SAAS,gBACd,QACG;AACH,MAAI,CAAC,uBAAuB,MAAM,GAAG;AACnC,UAAM,IAAI,UAAU,8CAA8C;AAAA,EACpE;AACA,QAAM,gBAAgB,OAAO,QAAQ;AACrC,QAAM,UAAU,SAAS,0BAAiC;AACxD,UAAM,IAAI;AAAA,MACR,GAAG,aAAa;AAAA,OAER,aAAa,gDACJ,aAAa;AAAA,IAChC;AAAA,EACF;AACA,SAAO,eAAe,SAAS,QAAQ;AAAA,IACrC,cAAc;AAAA,IACd,OAAO;AAAA,EACT,CAAC;AACD,0BAAwB,QAAQ,OAAO;AACvC,SAAO;AACT;AAUO,SAAS,sCAAyC,UAAsB;AAC7E,QAAM,wBAAwB,aAAa;AAC3C,QAAM,6BAA6B,aAAa;AAChD,QAAM,8BAA8B,aAAa;AACjD,eAAa,gBAAgB;AAC7B,eAAa,qBAAqB;AAClC,eAAa,sBAAsB;AACnC,MAAI;AACF,WAAO,yBAAyB,iCAAiC,QAAQ;AAAA,EAC3E,UAAE;AACA,iBAAa,gBAAgB;AAC7B,iBAAa,qBAAqB;AAClC,iBAAa,sBAAsB;AAAA,EACrC;AACF;AAEA,SAAS,uBAAuB,YAA4B;AAC1D,MAAI,eAAe,KAAK,UAAU,EAAG,QAAO,WAAW,MAAM,SAAS,MAAM;AAC5E,SAAO,cAAc;AACvB;",
+  "names": []
+}

package/dist/lib/development.d.ts

@@ -0,0 +1,2 @@
+/** @internal Build-time development gate; raw ESM without Vite is production-like. */
+export declare const isDevelopment: boolean;

package/dist/lib/development.js

@@ -0,0 +1,5 @@
+const isDevelopment = import.meta.env?.DEV ?? false;
+export {
+  isDevelopment
+};
+//# sourceMappingURL=development.js.map

package/dist/lib/development.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/development.ts"],
+  "sourcesContent": ["/** @internal Build-time development gate; raw ESM without Vite is production-like. */\nexport const isDevelopment = (\n  import.meta as ImportMeta & { env?: { readonly DEV?: boolean } }\n).env?.DEV ?? false;\n"],
+  "mappings": "AACO,MAAM,gBACX,YACA,KAAK,OAAO;",
+  "names": []
+}

package/dist/lib/element/children.d.ts

@@ -0,0 +1,16 @@
+import type { PibblElement, PibblNodeInput, PibblTextInput } from './types.js';
+type ChildReceiver = string | PibblElement<any>;
+/** Rejects a directly supplied foreign JSX root before Pibbl acquires resources. */
+export declare function assertCompatibleRootNode(node: unknown): void;
+/**
+ * Materializes one receiver's recursive container input into direct elements.
+ * Arrays and unkeyed Fragments are transparent; keyed Fragments remain entries.
+ */
+export declare function materializeContainerChildren(node: PibblNodeInput, receiver: ChildReceiver, options?: Readonly<{
+    validateKeys?: boolean;
+}>): readonly PibblElement<any>[];
+/** Prepares a policy descriptor for APIs that receive one element directly. */
+export declare function prepareElementPolicies(element: PibblElement<any>, receiver: string): PibblElement<any>;
+/** Materializes Text's recursive scalar content into one reusable string. */
+export declare function materializeTextChildren(node: PibblTextInput, receiver: ChildReceiver): string;
+export {};

package/dist/lib/element/children.js

@@ -0,0 +1,333 @@
+import { isPibblElement } from "./create-element.js";
+import { isFragmentElement } from "./fragment.js";
+import {
+  getElementPolicyDefinition,
+  getPolicyPreparationSource,
+  getElementSource,
+  setPolicyPreparationSource
+} from "./metadata.js";
+import { isSignal } from "../signals/graph.js";
+const REACT_ELEMENT_TYPE = /* @__PURE__ */ Symbol.for("react.element");
+const REACT_TRANSITIONAL_ELEMENT_TYPE = /* @__PURE__ */ Symbol.for(
+  "react.transitional.element"
+);
+function assertCompatibleRootNode(node) {
+  if (isSignal(node)) {
+    throw new Error(
+      "Pibbl root received a signal without a component receiver. Place the signal under a component or read it explicitly."
+    );
+  }
+  if (!node || typeof node !== "object" || isPibblElement(node)) return;
+  if (isReactElement(node)) throw reactElementError("Pibbl root");
+  if (!isPromiseLike(node) && !isAsyncIterable(node) && !Array.isArray(node) && !isIterable(node) && isForeignElementLike(node)) {
+    throw foreignElementError("Pibbl root");
+  }
+}
+function materializeContainerChildren(node, receiver, options = {}) {
+  const elements = [];
+  visitContainerNode(node, receiver, elements, [], false, true, /* @__PURE__ */ new Set());
+  if (options.validateKeys !== false) assertUniqueKeys(elements, receiver);
+  return Object.freeze(elements);
+}
+function prepareElementPolicies(element, receiver) {
+  if (!getElementPolicyDefinition(element.type)) return element;
+  const [prepared] = materializeContainerChildren(element, receiver);
+  return prepared;
+}
+function materializeTextChildren(node, receiver) {
+  const parts = [];
+  visitTextNode(node, receiver, parts, true, /* @__PURE__ */ new Set());
+  return parts.join("");
+}
+function visitContainerNode(node, receiver, elements, pendingPolicies = [], preservePolicies = false, allowSignals = true, ancestors) {
+  if (node === false || node === true || node === null || node === void 0 || node === "" || Object.is(node, 0) || Object.is(node, -0)) {
+    return;
+  }
+  if (isSignal(node)) {
+    if (receiver === "Pibbl root") {
+      throw new Error(
+        "Pibbl root received a signal without a component receiver. Place the signal under a component or read it explicitly."
+      );
+    }
+    if (!allowSignals) throw nestedSignalChild(receiver);
+    visitContainerNode(
+      node.get(),
+      receiver,
+      elements,
+      pendingPolicies,
+      preservePolicies,
+      false,
+      ancestors
+    );
+    return;
+  }
+  if (isPibblElement(node)) {
+    const policy = getElementPolicyDefinition(node.type);
+    if (policy) {
+      if (preservePolicies) {
+        elements.push(node);
+        return;
+      }
+      const policyChildren = materializeUnpreparedPolicyChildren(
+        node.props.children,
+        node,
+        allowSignals,
+        ancestors
+      );
+      if (policyChildren.length !== 1) {
+        throw new Error(
+          `${describeReceiver(node)} requires exactly one Pibbl element child after empty values are removed; received ${policyChildren.length}.`
+        );
+      }
+      visitContainerNode(
+        policyChildren[0],
+        node,
+        elements,
+        [...pendingPolicies, node],
+        preservePolicies,
+        allowSignals,
+        ancestors
+      );
+      return;
+    }
+    if (isFragmentElement(node) && node.key === void 0) {
+      visitContainerNode(
+        node.props.children,
+        receiver,
+        elements,
+        pendingPolicies,
+        preservePolicies,
+        allowSignals,
+        ancestors
+      );
+      return;
+    }
+    let prepared = node;
+    const preparationSource = getPolicyPreparationSource(node) ?? node;
+    for (const pendingPolicy of pendingPolicies) {
+      const definition = getElementPolicyDefinition(pendingPolicy.type);
+      if (!definition) {
+        throw new Error("Pibbl policy preparation metadata was lost.");
+      }
+      prepared = definition.prepare(pendingPolicy, prepared);
+    }
+    if (prepared !== node) {
+      setPolicyPreparationSource(prepared, preparationSource);
+    }
+    elements.push(prepared);
+    return;
+  }
+  if (typeof node === "string") {
+    throw invalidChild(receiver, "a non-empty string");
+  }
+  if (typeof node === "number") {
+    throw invalidChild(receiver, "a nonzero number");
+  }
+  if (typeof node === "function") {
+    throw invalidChild(receiver, "a function");
+  }
+  if (typeof node === "symbol") {
+    throw invalidChild(receiver, "a symbol");
+  }
+  if (typeof node !== "object") {
+    throw invalidChild(receiver, `an unsupported ${typeof node} value`);
+  }
+  if (isReactElement(node)) {
+    throw reactElementError(receiver);
+  }
+  if (isPromiseLike(node)) {
+    throw invalidChild(receiver, "a Promise");
+  }
+  if (isAsyncIterable(node)) {
+    throw invalidChild(receiver, "an async iterable");
+  }
+  if (Array.isArray(node)) {
+    withAcyclicContainer(node, receiver, ancestors, () => {
+      for (const child of node) {
+        visitContainerNode(
+          child,
+          receiver,
+          elements,
+          pendingPolicies,
+          preservePolicies,
+          allowSignals,
+          ancestors
+        );
+      }
+    });
+    return;
+  }
+  if (isIterable(node)) {
+    withAcyclicContainer(node, receiver, ancestors, () => {
+      for (const child of node) {
+        visitContainerNode(
+          child,
+          receiver,
+          elements,
+          pendingPolicies,
+          preservePolicies,
+          allowSignals,
+          ancestors
+        );
+      }
+    });
+    return;
+  }
+  if (isForeignElementLike(node)) {
+    throw foreignElementError(receiver);
+  }
+  throw invalidChild(receiver, "an unsupported object");
+}
+function materializeUnpreparedPolicyChildren(node, receiver, allowSignals, ancestors) {
+  const elements = [];
+  visitContainerNode(
+    node,
+    receiver,
+    elements,
+    [],
+    true,
+    allowSignals,
+    ancestors
+  );
+  assertUniqueKeys(elements, receiver);
+  return Object.freeze(elements);
+}
+function visitTextNode(node, receiver, parts, allowSignals, ancestors) {
+  if (node === false || node === true || node === null || node === void 0) {
+    return;
+  }
+  if (isSignal(node)) {
+    if (!allowSignals) throw nestedSignalChild(receiver);
+    visitTextNode(node.get(), receiver, parts, false, ancestors);
+    return;
+  }
+  if (typeof node === "string" || typeof node === "number") {
+    parts.push(String(node));
+    return;
+  }
+  if (isPibblElement(node)) {
+    throw invalidChild(receiver, "a Pibbl element inside textual content");
+  }
+  if (typeof node === "function") {
+    throw invalidChild(receiver, "a function");
+  }
+  if (typeof node === "symbol") {
+    throw invalidChild(receiver, "a symbol");
+  }
+  if (typeof node !== "object") {
+    throw invalidChild(receiver, `an unsupported ${typeof node} value`);
+  }
+  if (isReactElement(node)) {
+    throw reactElementError(receiver);
+  }
+  if (isPromiseLike(node)) {
+    throw invalidChild(receiver, "a Promise");
+  }
+  if (isAsyncIterable(node)) {
+    throw invalidChild(receiver, "an async iterable");
+  }
+  if (Array.isArray(node)) {
+    withAcyclicContainer(node, receiver, ancestors, () => {
+      for (const child of node) {
+        visitTextNode(child, receiver, parts, allowSignals, ancestors);
+      }
+    });
+    return;
+  }
+  if (isIterable(node)) {
+    withAcyclicContainer(node, receiver, ancestors, () => {
+      for (const child of node) {
+        visitTextNode(child, receiver, parts, allowSignals, ancestors);
+      }
+    });
+    return;
+  }
+  if (isForeignElementLike(node)) {
+    throw foreignElementError(receiver);
+  }
+  throw invalidChild(receiver, "an unsupported object");
+}
+function assertUniqueKeys(elements, receiver) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const element of elements) {
+    const key = element.key;
+    if (key === void 0) continue;
+    if (keys.has(key)) {
+      throw invalidChild(receiver, `duplicate Pibbl key "${key}"`);
+    }
+    keys.add(key);
+  }
+}
+function invalidChild(receiver, description) {
+  return new Error(
+    `${describeReceiver(receiver)} received ${description} as a Pibbl child.`
+  );
+}
+function nestedSignalChild(receiver) {
+  return invalidChild(
+    receiver,
+    "a signal inside a signal-resolved child structure"
+  );
+}
+function withAcyclicContainer(value, receiver, ancestors, visit) {
+  if (ancestors.has(value)) {
+    throw invalidChild(receiver, "a cyclic child structure");
+  }
+  ancestors.add(value);
+  try {
+    visit();
+  } finally {
+    ancestors.delete(value);
+  }
+}
+function reactElementError(receiver) {
+  return new Error(
+    `Pibbl received a React element. This file is using the React JSX runtime.
+Set jsxImportSource to "@pibbl/core" or add /** @jsxImportSource @pibbl/core */.
+Received by ${describeReceiver(receiver)}.`
+  );
+}
+function foreignElementError(receiver) {
+  return new Error(
+    `${describeReceiver(receiver)} received an element-like object that was not created by @pibbl/core as a Pibbl child.
+Check this file's JSX runtime and set jsxImportSource to "@pibbl/core".`
+  );
+}
+function describeReceiver(receiver) {
+  if (typeof receiver === "string") return receiver;
+  const name = receiver.type.name || "Anonymous";
+  const source = getElementSource(receiver);
+  return source ? `${name} at ${source.fileName}:${source.lineNumber}:${source.columnNumber}` : name;
+}
+function isReactElement(value) {
+  const brand = value.$$typeof;
+  return brand === REACT_ELEMENT_TYPE || brand === REACT_TRANSITIONAL_ELEMENT_TYPE;
+}
+function isForeignElementLike(value) {
+  if (!Object.prototype.hasOwnProperty.call(value, "type") || !Object.prototype.hasOwnProperty.call(value, "props")) {
+    return false;
+  }
+  try {
+    const type = value.type;
+    const props = value.props;
+    return (typeof type === "function" || typeof type === "string" || typeof type === "symbol") && (props === null || typeof props === "object");
+  } catch {
+    return false;
+  }
+}
+function isPromiseLike(value) {
+  return typeof value.then === "function";
+}
+function isAsyncIterable(value) {
+  return typeof value[Symbol.asyncIterator] === "function";
+}
+function isIterable(value) {
+  return typeof value[Symbol.iterator] === "function";
+}
+export {
+  assertCompatibleRootNode,
+  materializeContainerChildren,
+  materializeTextChildren,
+  prepareElementPolicies
+};
+//# sourceMappingURL=children.js.map