@number10/jsx-core 5.0.0

package/dist/nineslice-contract.d.ts

@@ -0,0 +1,107 @@
+import { SizeValue, TransformProps } from './core-props';
+import { PropsDefaultExtension } from './types';
+/** A rectangle in the source texture (texture-pixel coordinates) */
+export interface SliceRect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/**
+ * Portable props for the native NineSlice primitive.
+ *
+ * The portable NineSlice component passes texture identity and slice
+ * dimensions. The renderer resolves texture frame geometry, computes
+ * the 9 source regions, and derives target-space edge arrays from the
+ * resolved layout size — snapping once per axis to avoid sub-pixel seams.
+ */
+export interface NineSlicePrimitiveProps extends TransformProps {
+    /** Texture key */
+    texture: string;
+    /** Optional atlas frame name */
+    frame?: string | undefined;
+    /** Optional tint colour */
+    tint?: number | undefined;
+    /** Target display width (resolved by the layout system) */
+    width: SizeValue;
+    /** Target display height (resolved by the layout system) */
+    height: SizeValue;
+    /** Width of the left slice in source texture pixels */
+    leftWidth: number;
+    /** Width of the right slice in source texture pixels */
+    rightWidth: number;
+    /** Height of the top slice in source texture pixels (0 = 3-slice mode) */
+    topHeight: number;
+    /** Height of the bottom slice in source texture pixels (0 = 3-slice mode) */
+    bottomHeight: number;
+    /**
+     * Whether image smoothing is enabled when scaling segments.
+     * Default: false (prefer crisp rendering for UI textures).
+     */
+    imageSmoothingEnabled?: boolean | undefined;
+    /**
+     * When true, the element is rendered but excluded from layout calculations.
+     * Used for decorative background layers inside stack containers.
+     */
+    headless?: boolean | undefined;
+}
+/**
+ * Complete NineSlice props including JSX extension props (ref, key).
+ */
+export interface NineSlicePrimitivePropsComplete<TNode = unknown> extends NineSlicePrimitiveProps, PropsDefaultExtension<TNode> {
+}
+/**
+ * Compute the 9 source slice rectangles from a texture frame and slice widths.
+ *
+ * @param frameW  - Source texture / frame width in pixels
+ * @param frameH  - Source texture / frame height in pixels
+ * @param left    - Left slice width
+ * @param right   - Right slice width
+ * @param top     - Top slice height (0 for 3-slice mode)
+ * @param bottom  - Bottom slice height (0 for 3-slice mode)
+ * @returns 9-element tuple of source slice rects
+ */
+export declare function computeSourceSlices(frameW: number, frameH: number, left: number, right: number, top: number, bottom: number): readonly [
+    SliceRect,
+    SliceRect,
+    SliceRect,
+    SliceRect,
+    SliceRect,
+    SliceRect,
+    SliceRect,
+    SliceRect,
+    SliceRect
+];
+/**
+ * Compute 4 shared X edge positions for the target NineSlice.
+ *
+ * @param x          - Left edge of the target area
+ * @param width      - Total target width
+ * @param leftWidth  - Left slice width (in target pixels)
+ * @param rightWidth - Right slice width (in target pixels)
+ * @returns [left, left+leftWidth, right-rightWidth, right]
+ */
+export declare function computeTargetXs(x: number, width: number, leftWidth: number, rightWidth: number): readonly [number, number, number, number];
+/**
+ * Compute 4 shared Y edge positions for the target NineSlice.
+ *
+ * @param y           - Top edge of the target area
+ * @param height      - Total target height
+ * @param topHeight   - Top slice height (in target pixels)
+ * @param bottomHeight - Bottom slice height (in target pixels)
+ * @returns [top, top+topHeight, bottom-bottomHeight, bottom]
+ */
+export declare function computeTargetYs(y: number, height: number, topHeight: number, bottomHeight: number): readonly [number, number, number, number];
+/**
+ * Derive all 9 target rectangles from shared edge arrays.
+ *
+ * Since adjacent segments share edges, computing target rects this way
+ * guarantees zero overlap and zero gaps — provided the edge arrays have
+ * been snapped to the physical pixel grid by the renderer backend.
+ *
+ * @param xs - 4 shared X edges (must be monotonically non-decreasing)
+ * @param ys - 4 shared Y edges (must be monotonically non-decreasing)
+ * @returns 9 target rectangles with {x, y, w, h}
+ */
+export declare function deriveTargetRects(xs: readonly [number, number, number, number], ys: readonly [number, number, number, number]): readonly SliceRect[];
+//# sourceMappingURL=nineslice-contract.d.ts.map

package/dist/nineslice-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nineslice-contract.d.ts","sourceRoot":"","sources":["../src/nineslice-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAEpD,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC7D,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,2DAA2D;IAC3D,KAAK,EAAE,SAAS,CAAA;IAChB,4DAA4D;IAC5D,MAAM,EAAE,SAAS,CAAA;IACjB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAA;IACjB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAA;IAClB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAA;IACjB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B,CAAC,KAAK,GAAG,OAAO,CAC9D,SAAQ,uBAAuB,EAAE,qBAAqB,CAAC,KAAK,CAAC;CAAG;AAMlE;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,SAAS;IACV,SAAS;IACT,SAAS;IACT,SAAS;IACT,SAAS;IACT,SAAS;IACT,SAAS;IACT,SAAS;IACT,SAAS;IACT,SAAS;CACV,CAeA;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAE3C;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC7C,EAAE,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC5C,SAAS,SAAS,EAAE,CAWtB"}

package/dist/nineslice-contract.js

@@ -0,0 +1,60 @@
+function computeSourceSlices(frameW, frameH, left, right, top, bottom) {
+  const centerW = Math.max(0, frameW - left - right);
+  const centerH = Math.max(0, frameH - top - bottom);
+  return [
+    { x: 0, y: 0, w: left, h: top },
+    { x: left, y: 0, w: centerW, h: top },
+    { x: frameW - right, y: 0, w: right, h: top },
+    { x: 0, y: top, w: left, h: centerH },
+    { x: left, y: top, w: centerW, h: centerH },
+    { x: frameW - right, y: top, w: right, h: centerH },
+    { x: 0, y: frameH - bottom, w: left, h: bottom },
+    { x: left, y: frameH - bottom, w: centerW, h: bottom },
+    { x: frameW - right, y: frameH - bottom, w: right, h: bottom }
+  ];
+}
+function computeTargetXs(x, width, leftWidth, rightWidth) {
+  return [x, x + leftWidth, x + width - rightWidth, x + width];
+}
+function computeTargetYs(y, height, topHeight, bottomHeight) {
+  return [y, y + topHeight, y + height - bottomHeight, y + height];
+}
+const SEGMENT_EDGE_MAP = [
+  [0, 1, 0, 1],
+  // TL
+  [1, 2, 0, 1],
+  // Top
+  [2, 3, 0, 1],
+  // TR
+  [0, 1, 1, 2],
+  // Left
+  [1, 2, 1, 2],
+  // Center
+  [2, 3, 1, 2],
+  // Right
+  [0, 1, 2, 3],
+  // BL
+  [1, 2, 2, 3],
+  // Bottom
+  [2, 3, 2, 3]
+  // BR
+];
+function deriveTargetRects(xs, ys) {
+  const rects = [];
+  for (const [x0, x1, y0, y1] of SEGMENT_EDGE_MAP) {
+    rects.push({
+      x: xs[x0] ?? 0,
+      y: ys[y0] ?? 0,
+      w: Math.max(0, (xs[x1] ?? 0) - (xs[x0] ?? 0)),
+      h: Math.max(0, (ys[y1] ?? 0) - (ys[y0] ?? 0))
+    });
+  }
+  return rects;
+}
+export {
+  computeSourceSlices,
+  computeTargetXs,
+  computeTargetYs,
+  deriveTargetRects
+};
+//# sourceMappingURL=nineslice-contract.js.map

package/dist/nineslice-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nineslice-contract.js","sources":["../src/nineslice-contract.ts"],"sourcesContent":["/**\n * Portable NineSlice primitive contract — renderer-neutral.\n *\n * Defines the props interface for the native `nineslice` host primitive.\n * When a renderer declares the `nineslice` capability, the portable\n * NineSlice component renders a single `<nineslice>` element instead\n * of multiple `<image>` fragments.\n *\n * The portable layer passes texture info and slice dimensions\n * (leftWidth, rightWidth, topHeight, bottomHeight). The renderer:\n *\n * - Computes the 9 source slice regions from the texture frame geometry\n * - Receives the resolved target width/height from the layout system\n * - Applies the effective device/content scale\n * - Snaps shared edges to the physical pixel grid (once per axis)\n * - Derives all 9 target rectangles from snapped edges\n * - Draws all segments as a single draw operation\n */\n\nimport type { SizeValue, TransformProps } from './core-props'\nimport type { PropsDefaultExtension } from './types'\n\n/** A rectangle in the source texture (texture-pixel coordinates) */\nexport interface SliceRect {\n  readonly x: number\n  readonly y: number\n  readonly w: number\n  readonly h: number\n}\n\n/**\n * Portable props for the native NineSlice primitive.\n *\n * The portable NineSlice component passes texture identity and slice\n * dimensions. The renderer resolves texture frame geometry, computes\n * the 9 source regions, and derives target-space edge arrays from the\n * resolved layout size — snapping once per axis to avoid sub-pixel seams.\n */\nexport interface NineSlicePrimitiveProps extends TransformProps {\n  /** Texture key */\n  texture: string\n  /** Optional atlas frame name */\n  frame?: string | undefined\n  /** Optional tint colour */\n  tint?: number | undefined\n  /** Target display width (resolved by the layout system) */\n  width: SizeValue\n  /** Target display height (resolved by the layout system) */\n  height: SizeValue\n  /** Width of the left slice in source texture pixels */\n  leftWidth: number\n  /** Width of the right slice in source texture pixels */\n  rightWidth: number\n  /** Height of the top slice in source texture pixels (0 = 3-slice mode) */\n  topHeight: number\n  /** Height of the bottom slice in source texture pixels (0 = 3-slice mode) */\n  bottomHeight: number\n  /**\n   * Whether image smoothing is enabled when scaling segments.\n   * Default: false (prefer crisp rendering for UI textures).\n   */\n  imageSmoothingEnabled?: boolean | undefined\n  /**\n   * When true, the element is rendered but excluded from layout calculations.\n   * Used for decorative background layers inside stack containers.\n   */\n  headless?: boolean | undefined\n}\n\n/**\n * Complete NineSlice props including JSX extension props (ref, key).\n */\nexport interface NineSlicePrimitivePropsComplete<TNode = unknown>\n  extends NineSlicePrimitiveProps, PropsDefaultExtension<TNode> {}\n\n// ---------------------------------------------------------------------------\n// Slice computation helpers (portable, renderer-neutral)\n// ---------------------------------------------------------------------------\n\n/**\n * Compute the 9 source slice rectangles from a texture frame and slice widths.\n *\n * @param frameW  - Source texture / frame width in pixels\n * @param frameH  - Source texture / frame height in pixels\n * @param left    - Left slice width\n * @param right   - Right slice width\n * @param top     - Top slice height (0 for 3-slice mode)\n * @param bottom  - Bottom slice height (0 for 3-slice mode)\n * @returns 9-element tuple of source slice rects\n */\nexport function computeSourceSlices(\n  frameW: number,\n  frameH: number,\n  left: number,\n  right: number,\n  top: number,\n  bottom: number\n): readonly [\n  SliceRect,\n  SliceRect,\n  SliceRect,\n  SliceRect,\n  SliceRect,\n  SliceRect,\n  SliceRect,\n  SliceRect,\n  SliceRect,\n] {\n  const centerW = Math.max(0, frameW - left - right)\n  const centerH = Math.max(0, frameH - top - bottom)\n\n  return [\n    { x: 0, y: 0, w: left, h: top },\n    { x: left, y: 0, w: centerW, h: top },\n    { x: frameW - right, y: 0, w: right, h: top },\n    { x: 0, y: top, w: left, h: centerH },\n    { x: left, y: top, w: centerW, h: centerH },\n    { x: frameW - right, y: top, w: right, h: centerH },\n    { x: 0, y: frameH - bottom, w: left, h: bottom },\n    { x: left, y: frameH - bottom, w: centerW, h: bottom },\n    { x: frameW - right, y: frameH - bottom, w: right, h: bottom },\n  ]\n}\n\n/**\n * Compute 4 shared X edge positions for the target NineSlice.\n *\n * @param x          - Left edge of the target area\n * @param width      - Total target width\n * @param leftWidth  - Left slice width (in target pixels)\n * @param rightWidth - Right slice width (in target pixels)\n * @returns [left, left+leftWidth, right-rightWidth, right]\n */\nexport function computeTargetXs(\n  x: number,\n  width: number,\n  leftWidth: number,\n  rightWidth: number\n): readonly [number, number, number, number] {\n  return [x, x + leftWidth, x + width - rightWidth, x + width] as const\n}\n\n/**\n * Compute 4 shared Y edge positions for the target NineSlice.\n *\n * @param y           - Top edge of the target area\n * @param height      - Total target height\n * @param topHeight   - Top slice height (in target pixels)\n * @param bottomHeight - Bottom slice height (in target pixels)\n * @returns [top, top+topHeight, bottom-bottomHeight, bottom]\n */\nexport function computeTargetYs(\n  y: number,\n  height: number,\n  topHeight: number,\n  bottomHeight: number\n): readonly [number, number, number, number] {\n  return [y, y + topHeight, y + height - bottomHeight, y + height] as const\n}\n\n/**\n * Edge index pairs for segment target rectangles.\n * Each entry: [xsLeftIndex, xsRightIndex, ysTopIndex, ysBottomIndex]\n */\nconst SEGMENT_EDGE_MAP: readonly (readonly [number, number, number, number])[] = [\n  [0, 1, 0, 1], // TL\n  [1, 2, 0, 1], // Top\n  [2, 3, 0, 1], // TR\n  [0, 1, 1, 2], // Left\n  [1, 2, 1, 2], // Center\n  [2, 3, 1, 2], // Right\n  [0, 1, 2, 3], // BL\n  [1, 2, 2, 3], // Bottom\n  [2, 3, 2, 3], // BR\n] as const\n\n/**\n * Derive all 9 target rectangles from shared edge arrays.\n *\n * Since adjacent segments share edges, computing target rects this way\n * guarantees zero overlap and zero gaps — provided the edge arrays have\n * been snapped to the physical pixel grid by the renderer backend.\n *\n * @param xs - 4 shared X edges (must be monotonically non-decreasing)\n * @param ys - 4 shared Y edges (must be monotonically non-decreasing)\n * @returns 9 target rectangles with {x, y, w, h}\n */\nexport function deriveTargetRects(\n  xs: readonly [number, number, number, number],\n  ys: readonly [number, number, number, number]\n): readonly SliceRect[] {\n  const rects: SliceRect[] = []\n  for (const [x0, x1, y0, y1] of SEGMENT_EDGE_MAP) {\n    rects.push({\n      x: xs[x0] ?? 0,\n      y: ys[y0] ?? 0,\n      w: Math.max(0, (xs[x1] ?? 0) - (xs[x0] ?? 0)),\n      h: Math.max(0, (ys[y1] ?? 0) - (ys[y0] ?? 0)),\n    })\n  }\n  return rects\n}\n"],"names":[],"mappings":"AA0FO,SAAS,oBACd,QACA,QACA,MACA,OACA,KACA,QAWA;AACA,QAAM,UAAU,KAAK,IAAI,GAAG,SAAS,OAAO,KAAK;AACjD,QAAM,UAAU,KAAK,IAAI,GAAG,SAAS,MAAM,MAAM;AAEjD,SAAO;AAAA,IACL,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,MAAM,GAAG,IAAA;AAAA,IAC1B,EAAE,GAAG,MAAM,GAAG,GAAG,GAAG,SAAS,GAAG,IAAA;AAAA,IAChC,EAAE,GAAG,SAAS,OAAO,GAAG,GAAG,GAAG,OAAO,GAAG,IAAA;AAAA,IACxC,EAAE,GAAG,GAAG,GAAG,KAAK,GAAG,MAAM,GAAG,QAAA;AAAA,IAC5B,EAAE,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,QAAA;AAAA,IAClC,EAAE,GAAG,SAAS,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,QAAA;AAAA,IAC1C,EAAE,GAAG,GAAG,GAAG,SAAS,QAAQ,GAAG,MAAM,GAAG,OAAA;AAAA,IACxC,EAAE,GAAG,MAAM,GAAG,SAAS,QAAQ,GAAG,SAAS,GAAG,OAAA;AAAA,IAC9C,EAAE,GAAG,SAAS,OAAO,GAAG,SAAS,QAAQ,GAAG,OAAO,GAAG,OAAA;AAAA,EAAO;AAEjE;AAWO,SAAS,gBACd,GACA,OACA,WACA,YAC2C;AAC3C,SAAO,CAAC,GAAG,IAAI,WAAW,IAAI,QAAQ,YAAY,IAAI,KAAK;AAC7D;AAWO,SAAS,gBACd,GACA,QACA,WACA,cAC2C;AAC3C,SAAO,CAAC,GAAG,IAAI,WAAW,IAAI,SAAS,cAAc,IAAI,MAAM;AACjE;AAMA,MAAM,mBAA2E;AAAA,EAC/E,CAAC,GAAG,GAAG,GAAG,CAAC;AAAA;AAAA,EACX,CAAC,GAAG,GAAG,GAAG,CAAC;AAAA;AAAA,EACX,CAAC,GAAG,GAAG,GAAG,CAAC;AAAA;AAAA,EACX,CAAC,GAAG,GAAG,GAAG,CAAC;AAAA;AAAA,EACX,CAAC,GAAG,GAAG,GAAG,CAAC;AAAA;AAAA,EACX,CAAC,GAAG,GAAG,GAAG,CAAC;AAAA;AAAA,EACX,CAAC,GAAG,GAAG,GAAG,CAAC;AAAA;AAAA,EACX,CAAC,GAAG,GAAG,GAAG,CAAC;AAAA;AAAA,EACX,CAAC,GAAG,GAAG,GAAG,CAAC;AAAA;AACb;AAaO,SAAS,kBACd,IACA,IACsB;AACtB,QAAM,QAAqB,CAAA;AAC3B,aAAW,CAAC,IAAI,IAAI,IAAI,EAAE,KAAK,kBAAkB;AAC/C,UAAM,KAAK;AAAA,MACT,GAAG,GAAG,EAAE,KAAK;AAAA,MACb,GAAG,GAAG,EAAE,KAAK;AAAA,MACb,GAAG,KAAK,IAAI,IAAI,GAAG,EAAE,KAAK,MAAM,GAAG,EAAE,KAAK,EAAE;AAAA,MAC5C,GAAG,KAAK,IAAI,IAAI,GAAG,EAAE,KAAK,MAAM,GAAG,EAAE,KAAK,EAAE;AAAA,IAAA,CAC7C;AAAA,EACH;AACA,SAAO;AACT;"}

package/dist/placeholder.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function logNotYetImplemented(componentName, surface) {
+  const renderer = surface?.raw ? surface.raw.constructor?.name ?? "unknown" : "unknown";
+  if (typeof console !== "undefined" && console.warn) {
+    console.warn(
+      `[@number10/jsx-core] ${componentName}: not yet implemented for renderer "${renderer}". Using portable fallback.`
+    );
+  }
+}
+exports.logNotYetImplemented = logNotYetImplemented;
+//# sourceMappingURL=placeholder.cjs.map

package/dist/placeholder.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder.cjs","sources":["../src/placeholder.ts"],"sourcesContent":["/**\n * Placeholder utilities — renderer-neutral \"not yet implemented\" fallback.\n *\n * Portable components that need renderer-specific integration (e.g., SVG\n * texture loading, overlay mounting) can use these helpers to provide a\n * visible fallback when a renderer hasn't implemented the feature yet.\n *\n * ## Usage\n *\n * ```typescript\n * // In a portable component that needs renderer integration:\n * import { logNotYetImplemented } from '@number10/jsx-core'\n *\n * export function MyPortableComponent(props: MyProps) {\n *   const surface = useSurface()\n *\n *   if (!surface?.capabilities.has('svg-texture')) {\n *     logNotYetImplemented('Icon', surface)\n *     return <Text text=\"[Icon not implemented]\" />\n *   }\n *\n *   // ... normal implementation\n * }\n * ```\n */\n\n// ---------------------------------------------------------------------------\n// NotYetImplemented — visible fallback component\n// ---------------------------------------------------------------------------\n\n/**\n * Log a structured warning for a renderer that hasn't implemented a feature.\n *\n * The warning includes the component name and renderer identity so developers\n * can track which components are still missing implementation.\n *\n * @param componentName - Name of the component that is not yet implemented\n * @param surface - Optional surface context (used to identify the renderer)\n *\n * @example\n * ```typescript\n * logNotYetImplemented('Icon', surface)\n * // → \"[@number10/jsx-core] Icon: not yet implemented for this renderer\"\n * ```\n */\nexport function logNotYetImplemented(\n  componentName: string,\n  surface?: { readonly raw?: unknown } | undefined\n): void {\n  const renderer = surface?.raw\n    ? ((surface.raw as { constructor?: { name?: string } }).constructor?.name ?? 'unknown')\n    : 'unknown'\n\n  if (typeof console !== 'undefined' && console.warn) {\n    console.warn(\n      `[@number10/jsx-core] ${componentName}: not yet implemented for renderer \"${renderer}\". ` +\n        `Using portable fallback.`\n    )\n  }\n}\n"],"names":[],"mappings":";;AA6CO,SAAS,qBACd,eACA,SACM;AACN,QAAM,WAAW,SAAS,MACpB,QAAQ,IAA4C,aAAa,QAAQ,YAC3E;AAEJ,MAAI,OAAO,YAAY,eAAe,QAAQ,MAAM;AAClD,YAAQ;AAAA,MACN,wBAAwB,aAAa,uCAAuC,QAAQ;AAAA,IAAA;AAAA,EAGxF;AACF;;"}

package/dist/placeholder.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Placeholder utilities — renderer-neutral "not yet implemented" fallback.
+ *
+ * Portable components that need renderer-specific integration (e.g., SVG
+ * texture loading, overlay mounting) can use these helpers to provide a
+ * visible fallback when a renderer hasn't implemented the feature yet.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // In a portable component that needs renderer integration:
+ * import { logNotYetImplemented } from '@number10/jsx-core'
+ *
+ * export function MyPortableComponent(props: MyProps) {
+ *   const surface = useSurface()
+ *
+ *   if (!surface?.capabilities.has('svg-texture')) {
+ *     logNotYetImplemented('Icon', surface)
+ *     return <Text text="[Icon not implemented]" />
+ *   }
+ *
+ *   // ... normal implementation
+ * }
+ * ```
+ */
+/**
+ * Log a structured warning for a renderer that hasn't implemented a feature.
+ *
+ * The warning includes the component name and renderer identity so developers
+ * can track which components are still missing implementation.
+ *
+ * @param componentName - Name of the component that is not yet implemented
+ * @param surface - Optional surface context (used to identify the renderer)
+ *
+ * @example
+ * ```typescript
+ * logNotYetImplemented('Icon', surface)
+ * // → "[@number10/jsx-core] Icon: not yet implemented for this renderer"
+ * ```
+ */
+export declare function logNotYetImplemented(componentName: string, surface?: {
+    readonly raw?: unknown;
+} | undefined): void;
+//# sourceMappingURL=placeholder.d.ts.map

package/dist/placeholder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder.d.ts","sourceRoot":"","sources":["../src/placeholder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GAC/C,IAAI,CAWN"}

package/dist/placeholder.js

@@ -0,0 +1,12 @@
+function logNotYetImplemented(componentName, surface) {
+  const renderer = surface?.raw ? surface.raw.constructor?.name ?? "unknown" : "unknown";
+  if (typeof console !== "undefined" && console.warn) {
+    console.warn(
+      `[@number10/jsx-core] ${componentName}: not yet implemented for renderer "${renderer}". Using portable fallback.`
+    );
+  }
+}
+export {
+  logNotYetImplemented
+};
+//# sourceMappingURL=placeholder.js.map

package/dist/placeholder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder.js","sources":["../src/placeholder.ts"],"sourcesContent":["/**\n * Placeholder utilities — renderer-neutral \"not yet implemented\" fallback.\n *\n * Portable components that need renderer-specific integration (e.g., SVG\n * texture loading, overlay mounting) can use these helpers to provide a\n * visible fallback when a renderer hasn't implemented the feature yet.\n *\n * ## Usage\n *\n * ```typescript\n * // In a portable component that needs renderer integration:\n * import { logNotYetImplemented } from '@number10/jsx-core'\n *\n * export function MyPortableComponent(props: MyProps) {\n *   const surface = useSurface()\n *\n *   if (!surface?.capabilities.has('svg-texture')) {\n *     logNotYetImplemented('Icon', surface)\n *     return <Text text=\"[Icon not implemented]\" />\n *   }\n *\n *   // ... normal implementation\n * }\n * ```\n */\n\n// ---------------------------------------------------------------------------\n// NotYetImplemented — visible fallback component\n// ---------------------------------------------------------------------------\n\n/**\n * Log a structured warning for a renderer that hasn't implemented a feature.\n *\n * The warning includes the component name and renderer identity so developers\n * can track which components are still missing implementation.\n *\n * @param componentName - Name of the component that is not yet implemented\n * @param surface - Optional surface context (used to identify the renderer)\n *\n * @example\n * ```typescript\n * logNotYetImplemented('Icon', surface)\n * // → \"[@number10/jsx-core] Icon: not yet implemented for this renderer\"\n * ```\n */\nexport function logNotYetImplemented(\n  componentName: string,\n  surface?: { readonly raw?: unknown } | undefined\n): void {\n  const renderer = surface?.raw\n    ? ((surface.raw as { constructor?: { name?: string } }).constructor?.name ?? 'unknown')\n    : 'unknown'\n\n  if (typeof console !== 'undefined' && console.warn) {\n    console.warn(\n      `[@number10/jsx-core] ${componentName}: not yet implemented for renderer \"${renderer}\". ` +\n        `Using portable fallback.`\n    )\n  }\n}\n"],"names":[],"mappings":"AA6CO,SAAS,qBACd,eACA,SACM;AACN,QAAM,WAAW,SAAS,MACpB,QAAQ,IAA4C,aAAa,QAAQ,YAC3E;AAEJ,MAAI,OAAO,YAAY,eAAe,QAAQ,MAAM;AAClD,YAAQ;AAAA,MACN,wBAAwB,aAAa,uCAAuC,QAAQ;AAAA,IAAA;AAAA,EAGxF;AACF;"}

package/dist/portal.cjs

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const hooks = require("./hooks.cjs");
+function usePortalSurface(options = {}) {
+  const surfaceContext = hooks.useSurface();
+  const adapter = surfaceContext?.adapter;
+  const parentSurface = surfaceContext?.rootSurface ?? (surfaceContext?.raw ? findParentSurface(adapter, surfaceContext.raw) : void 0);
+  const [portalSurface, setPortalSurface] = hooks.useState(null);
+  const portalRef = hooks.useRef(null);
+  const [error, setError] = hooks.useState(null);
+  const depthRef = hooks.useRef(options.depth ?? 1e3);
+  const mountedRef = hooks.useRef(false);
+  hooks.useEffect(() => {
+    if (!adapter) {
+      setError("No SurfaceAdapter available — cannot create portal");
+      return;
+    }
+    if (!parentSurface) {
+      setError("No parent RootSurface found — cannot create portal");
+      return;
+    }
+    if (mountedRef.current) return;
+    mountedRef.current = true;
+    const depth = options.depth ?? 1e3;
+    depthRef.current = depth;
+    try {
+      const created = adapter.createRoot({
+        kind: "portal",
+        parent: parentSurface,
+        zIndex: depth,
+        width: surfaceContext?.viewport.width ?? 0,
+        height: surfaceContext?.viewport.height ?? 0,
+        ...options.id ? { id: options.id } : {}
+      });
+      portalRef.current = created;
+      setPortalSurface(created);
+      setError(null);
+    } catch (e) {
+      setError(`Failed to create portal surface: ${e.message}`);
+    }
+    return () => {
+      mountedRef.current = false;
+      const current = portalRef.current;
+      if (current) {
+        portalRef.current = null;
+        setPortalSurface(null);
+        try {
+          adapter.destroyRoot(current);
+        } catch {
+        }
+      }
+    };
+  }, []);
+  const update = (updates) => {
+    const current = portalRef.current;
+    if (!current || !adapter) return;
+    if (updates.depth !== void 0) depthRef.current = updates.depth;
+    adapter.updateRoot(current, {
+      ...updates.depth !== void 0 ? { zIndex: updates.depth } : {},
+      ...updates.width !== void 0 ? { width: updates.width } : {},
+      ...updates.height !== void 0 ? { height: updates.height } : {}
+    });
+  };
+  const destroy = () => {
+    const current = portalRef.current;
+    if (current && adapter) {
+      portalRef.current = null;
+      setPortalSurface(null);
+      try {
+        adapter.destroyRoot(current);
+      } catch {
+      }
+      mountedRef.current = false;
+    }
+  };
+  return {
+    surface: portalSurface,
+    error,
+    update,
+    destroy,
+    vdom: surfaceContext?.vdom
+  };
+}
+function findParentSurface(adapter, target) {
+  if (!adapter || !adapter.getRootByTarget) return void 0;
+  return adapter.getRootByTarget(target);
+}
+exports.usePortalSurface = usePortalSurface;
+//# sourceMappingURL=portal.cjs.map

package/dist/portal.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal.cjs","sources":["../src/portal.ts"],"sourcesContent":["/**\n * Portable portal surface hook — renderer-neutral overlay root management.\n *\n * Manages the lifecycle of a portal RootSurface (create/update/destroy)\n * using the SurfaceAdapter stored on the current SurfaceContext.\n *\n * The actual VDOM mounting of children is left to the renderer-specific\n * Portal component (e.g., @number10/jsx-phaser's Portal.tsx), which calls\n * this hook and renders into `surface.root`.\n *\n * @example\n * ```typescript\n * // In a Phaser Portal component:\n * import { usePortalSurface } from '@number10/jsx-core'\n *\n * function Portal(props) {\n *   const { surface, error } = usePortalSurface({\n *     depth: props.depth ?? 1000,\n *     id: props.id,\n *   })\n *\n *   if (error) return null\n *   if (!surface) return null\n *\n *   // Mount children into surface.root (renderer-specific)\n *   // ...\n * }\n * ```\n */\n\nimport { useEffect, useRef, useState, useSurface } from './hooks'\nimport type { RootSurface, SurfaceAdapter, SurfaceContext } from './host-adapter'\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Options for usePortalSurface */\nexport interface UsePortalSurfaceOptions {\n  /** Z-depth for the portal (higher = on top of others) */\n  depth?: number\n  /** Optional unique portal ID */\n  id?: string\n  /**\n   * Block input events from passing through the portal area.\n   * The renderer adapter is responsible for implementing the actual\n   * event blocking (e.g., gesture blocker containers in Phaser).\n   */\n  blockEvents?: boolean\n}\n\n/** Result of usePortalSurface */\nexport interface UsePortalSurfaceResult {\n  /**\n   * The portal RootSurface, or null if not yet created.\n   * Renderers mount children into `surface.root`.\n   */\n  surface: RootSurface | null\n  /**\n   * Error message if portal creation failed.\n   * Component should render nothing when this is set.\n   */\n  error: string | null\n  /**\n   * Update the portal's depth or viewport dimensions.\n   * Call when depth prop changes or on viewport resize.\n   */\n  update: (updates: { depth?: number; width?: number; height?: number }) => void\n  /**\n   * Explicitly destroy the portal surface.\n   * Automatically called on unmount via useEffect cleanup.\n   */\n  destroy: () => void\n  /**\n   * Renderer-bound VDOM operations for mounting children.\n   * Portable components use this instead of importing renderer-specific\n   * mount/patchVNode/unmount to avoid multi-renderer conflicts.\n   */\n  vdom: SurfaceContext['vdom']\n}\n\n// ---------------------------------------------------------------------------\n// usePortalSurface\n// ---------------------------------------------------------------------------\n\n/**\n * Portable hook that creates and manages a portal RootSurface.\n *\n * Uses the SurfaceAdapter from the current SurfaceContext to create\n * a portal surface as a child of the parent surface. The hook handles\n * lifecycle: create on mount, update on option changes, destroy on unmount.\n *\n * @param options - Portal configuration\n * @returns Portal surface handle with update/destroy methods\n *\n * @migration(audit:surface-access) Phase 6B — portable portal surface lifecycle.\n *   Replaces manual createRoot/destroyRoot in renderer-specific Portal components.\n */\nexport function usePortalSurface(options: UsePortalSurfaceOptions = {}): UsePortalSurfaceResult {\n  const surfaceContext = useSurface()\n  const adapter: SurfaceAdapter | undefined = surfaceContext?.adapter\n  const parentSurface: RootSurface | undefined =\n    surfaceContext?.rootSurface ??\n    (surfaceContext?.raw ? findParentSurface(adapter, surfaceContext.raw) : undefined)\n\n  const [portalSurface, setPortalSurface] = useState<RootSurface | null>(null)\n  const portalRef = useRef<RootSurface | null>(null)\n  const [error, setError] = useState<string | null>(null)\n  const depthRef = useRef(options.depth ?? 1000)\n\n  // Track whether we've mounted to avoid double-init\n  const mountedRef = useRef(false)\n\n  // Create portal surface on mount\n  useEffect(() => {\n    if (!adapter) {\n      setError('No SurfaceAdapter available — cannot create portal')\n      return\n    }\n\n    if (!parentSurface) {\n      setError('No parent RootSurface found — cannot create portal')\n      return\n    }\n\n    if (mountedRef.current) return\n    mountedRef.current = true\n\n    const depth = options.depth ?? 1000\n    depthRef.current = depth\n\n    try {\n      const created = adapter.createRoot({\n        kind: 'portal',\n        parent: parentSurface,\n        zIndex: depth,\n        width: surfaceContext?.viewport.width ?? 0,\n        height: surfaceContext?.viewport.height ?? 0,\n        ...(options.id ? { id: options.id } : {}),\n      })\n\n      portalRef.current = created\n      setPortalSurface(created)\n      setError(null)\n    } catch (e) {\n      setError(`Failed to create portal surface: ${(e as Error).message}`)\n    }\n\n    return () => {\n      mountedRef.current = false\n      const current = portalRef.current\n      if (current) {\n        portalRef.current = null\n        setPortalSurface(null)\n        try {\n          adapter.destroyRoot(current)\n        } catch {\n          // Surface may already be destroyed by scene shutdown\n        }\n      }\n    }\n    // Only run on mount\n  }, [])\n\n  const update = (updates: { depth?: number; width?: number; height?: number }) => {\n    const current = portalRef.current\n    if (!current || !adapter) return\n\n    if (updates.depth !== undefined) depthRef.current = updates.depth\n\n    adapter.updateRoot(current, {\n      ...(updates.depth !== undefined ? { zIndex: updates.depth } : {}),\n      ...(updates.width !== undefined ? { width: updates.width } : {}),\n      ...(updates.height !== undefined ? { height: updates.height } : {}),\n    })\n  }\n\n  const destroy = () => {\n    const current = portalRef.current\n    if (current && adapter) {\n      portalRef.current = null\n      setPortalSurface(null)\n      try {\n        adapter.destroyRoot(current)\n      } catch {\n        // Surface may already be destroyed\n      }\n      mountedRef.current = false\n    }\n  }\n\n  return {\n    surface: portalSurface,\n    error,\n    update,\n    destroy,\n    vdom: surfaceContext?.vdom,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Find the parent RootSurface for a given renderer-native target.\n * Scans the adapter's registered surfaces for one whose raw target matches.\n */\nfunction findParentSurface(\n  adapter: SurfaceAdapter | undefined,\n  target: unknown\n): RootSurface | undefined {\n  if (!adapter || !adapter.getRootByTarget) return undefined\n  return adapter.getRootByTarget(target)\n}\n"],"names":["useSurface","useState","useRef","useEffect"],"mappings":";;;AAkGO,SAAS,iBAAiB,UAAmC,IAA4B;AAC9F,QAAM,iBAAiBA,MAAAA,WAAA;AACvB,QAAM,UAAsC,gBAAgB;AAC5D,QAAM,gBACJ,gBAAgB,gBACf,gBAAgB,MAAM,kBAAkB,SAAS,eAAe,GAAG,IAAI;AAE1E,QAAM,CAAC,eAAe,gBAAgB,IAAIC,MAAAA,SAA6B,IAAI;AAC3E,QAAM,YAAYC,MAAAA,OAA2B,IAAI;AACjD,QAAM,CAAC,OAAO,QAAQ,IAAID,MAAAA,SAAwB,IAAI;AACtD,QAAM,WAAWC,MAAAA,OAAO,QAAQ,SAAS,GAAI;AAG7C,QAAM,aAAaA,MAAAA,OAAO,KAAK;AAG/BC,QAAAA,UAAU,MAAM;AACd,QAAI,CAAC,SAAS;AACZ,eAAS,oDAAoD;AAC7D;AAAA,IACF;AAEA,QAAI,CAAC,eAAe;AAClB,eAAS,oDAAoD;AAC7D;AAAA,IACF;AAEA,QAAI,WAAW,QAAS;AACxB,eAAW,UAAU;AAErB,UAAM,QAAQ,QAAQ,SAAS;AAC/B,aAAS,UAAU;AAEnB,QAAI;AACF,YAAM,UAAU,QAAQ,WAAW;AAAA,QACjC,MAAM;AAAA,QACN,QAAQ;AAAA,QACR,QAAQ;AAAA,QACR,OAAO,gBAAgB,SAAS,SAAS;AAAA,QACzC,QAAQ,gBAAgB,SAAS,UAAU;AAAA,QAC3C,GAAI,QAAQ,KAAK,EAAE,IAAI,QAAQ,GAAA,IAAO,CAAA;AAAA,MAAC,CACxC;AAED,gBAAU,UAAU;AACpB,uBAAiB,OAAO;AACxB,eAAS,IAAI;AAAA,IACf,SAAS,GAAG;AACV,eAAS,oCAAqC,EAAY,OAAO,EAAE;AAAA,IACrE;AAEA,WAAO,MAAM;AACX,iBAAW,UAAU;AACrB,YAAM,UAAU,UAAU;AAC1B,UAAI,SAAS;AACX,kBAAU,UAAU;AACpB,yBAAiB,IAAI;AACrB,YAAI;AACF,kBAAQ,YAAY,OAAO;AAAA,QAC7B,QAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF;AAAA,EAEF,GAAG,CAAA,CAAE;AAEL,QAAM,SAAS,CAAC,YAAiE;AAC/E,UAAM,UAAU,UAAU;AAC1B,QAAI,CAAC,WAAW,CAAC,QAAS;AAE1B,QAAI,QAAQ,UAAU,OAAW,UAAS,UAAU,QAAQ;AAE5D,YAAQ,WAAW,SAAS;AAAA,MAC1B,GAAI,QAAQ,UAAU,SAAY,EAAE,QAAQ,QAAQ,MAAA,IAAU,CAAA;AAAA,MAC9D,GAAI,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,MAAA,IAAU,CAAA;AAAA,MAC7D,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,WAAW,CAAA;AAAA,IAAC,CAClE;AAAA,EACH;AAEA,QAAM,UAAU,MAAM;AACpB,UAAM,UAAU,UAAU;AAC1B,QAAI,WAAW,SAAS;AACtB,gBAAU,UAAU;AACpB,uBAAiB,IAAI;AACrB,UAAI;AACF,gBAAQ,YAAY,OAAO;AAAA,MAC7B,QAAQ;AAAA,MAER;AACA,iBAAW,UAAU;AAAA,IACvB;AAAA,EACF;AAEA,SAAO;AAAA,IACL,SAAS;AAAA,IACT;AAAA,IACA;AAAA,IACA;AAAA,IACA,MAAM,gBAAgB;AAAA,EAAA;AAE1B;AAUA,SAAS,kBACP,SACA,QACyB;AACzB,MAAI,CAAC,WAAW,CAAC,QAAQ,gBAAiB,QAAO;AACjD,SAAO,QAAQ,gBAAgB,MAAM;AACvC;;"}

package/dist/portal.d.ts

@@ -0,0 +1,62 @@
+import { RootSurface, SurfaceContext } from './host-adapter';
+/** Options for usePortalSurface */
+export interface UsePortalSurfaceOptions {
+    /** Z-depth for the portal (higher = on top of others) */
+    depth?: number;
+    /** Optional unique portal ID */
+    id?: string;
+    /**
+     * Block input events from passing through the portal area.
+     * The renderer adapter is responsible for implementing the actual
+     * event blocking (e.g., gesture blocker containers in Phaser).
+     */
+    blockEvents?: boolean;
+}
+/** Result of usePortalSurface */
+export interface UsePortalSurfaceResult {
+    /**
+     * The portal RootSurface, or null if not yet created.
+     * Renderers mount children into `surface.root`.
+     */
+    surface: RootSurface | null;
+    /**
+     * Error message if portal creation failed.
+     * Component should render nothing when this is set.
+     */
+    error: string | null;
+    /**
+     * Update the portal's depth or viewport dimensions.
+     * Call when depth prop changes or on viewport resize.
+     */
+    update: (updates: {
+        depth?: number;
+        width?: number;
+        height?: number;
+    }) => void;
+    /**
+     * Explicitly destroy the portal surface.
+     * Automatically called on unmount via useEffect cleanup.
+     */
+    destroy: () => void;
+    /**
+     * Renderer-bound VDOM operations for mounting children.
+     * Portable components use this instead of importing renderer-specific
+     * mount/patchVNode/unmount to avoid multi-renderer conflicts.
+     */
+    vdom: SurfaceContext['vdom'];
+}
+/**
+ * Portable hook that creates and manages a portal RootSurface.
+ *
+ * Uses the SurfaceAdapter from the current SurfaceContext to create
+ * a portal surface as a child of the parent surface. The hook handles
+ * lifecycle: create on mount, update on option changes, destroy on unmount.
+ *
+ * @param options - Portal configuration
+ * @returns Portal surface handle with update/destroy methods
+ *
+ * @migration(audit:surface-access) Phase 6B — portable portal surface lifecycle.
+ *   Replaces manual createRoot/destroyRoot in renderer-specific Portal components.
+ */
+export declare function usePortalSurface(options?: UsePortalSurfaceOptions): UsePortalSurfaceResult;
+//# sourceMappingURL=portal.d.ts.map

package/dist/portal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal.d.ts","sourceRoot":"","sources":["../src/portal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAkB,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAMjF,mCAAmC;AACnC,MAAM,WAAW,uBAAuB;IACtC,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gCAAgC;IAChC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,iCAAiC;AACjC,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;IAC3B;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;OAGG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IAC9E;;;OAGG;IACH,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB;;;;OAIG;IACH,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;CAC7B;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,sBAAsB,CAoG9F"}

package/dist/portal.js

@@ -0,0 +1,89 @@
+import { useSurface, useState, useRef, useEffect } from "./hooks.js";
+function usePortalSurface(options = {}) {
+  const surfaceContext = useSurface();
+  const adapter = surfaceContext?.adapter;
+  const parentSurface = surfaceContext?.rootSurface ?? (surfaceContext?.raw ? findParentSurface(adapter, surfaceContext.raw) : void 0);
+  const [portalSurface, setPortalSurface] = useState(null);
+  const portalRef = useRef(null);
+  const [error, setError] = useState(null);
+  const depthRef = useRef(options.depth ?? 1e3);
+  const mountedRef = useRef(false);
+  useEffect(() => {
+    if (!adapter) {
+      setError("No SurfaceAdapter available — cannot create portal");
+      return;
+    }
+    if (!parentSurface) {
+      setError("No parent RootSurface found — cannot create portal");
+      return;
+    }
+    if (mountedRef.current) return;
+    mountedRef.current = true;
+    const depth = options.depth ?? 1e3;
+    depthRef.current = depth;
+    try {
+      const created = adapter.createRoot({
+        kind: "portal",
+        parent: parentSurface,
+        zIndex: depth,
+        width: surfaceContext?.viewport.width ?? 0,
+        height: surfaceContext?.viewport.height ?? 0,
+        ...options.id ? { id: options.id } : {}
+      });
+      portalRef.current = created;
+      setPortalSurface(created);
+      setError(null);
+    } catch (e) {
+      setError(`Failed to create portal surface: ${e.message}`);
+    }
+    return () => {
+      mountedRef.current = false;
+      const current = portalRef.current;
+      if (current) {
+        portalRef.current = null;
+        setPortalSurface(null);
+        try {
+          adapter.destroyRoot(current);
+        } catch {
+        }
+      }
+    };
+  }, []);
+  const update = (updates) => {
+    const current = portalRef.current;
+    if (!current || !adapter) return;
+    if (updates.depth !== void 0) depthRef.current = updates.depth;
+    adapter.updateRoot(current, {
+      ...updates.depth !== void 0 ? { zIndex: updates.depth } : {},
+      ...updates.width !== void 0 ? { width: updates.width } : {},
+      ...updates.height !== void 0 ? { height: updates.height } : {}
+    });
+  };
+  const destroy = () => {
+    const current = portalRef.current;
+    if (current && adapter) {
+      portalRef.current = null;
+      setPortalSurface(null);
+      try {
+        adapter.destroyRoot(current);
+      } catch {
+      }
+      mountedRef.current = false;
+    }
+  };
+  return {
+    surface: portalSurface,
+    error,
+    update,
+    destroy,
+    vdom: surfaceContext?.vdom
+  };
+}
+function findParentSurface(adapter, target) {
+  if (!adapter || !adapter.getRootByTarget) return void 0;
+  return adapter.getRootByTarget(target);
+}
+export {
+  usePortalSurface
+};
+//# sourceMappingURL=portal.js.map

package/dist/portal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal.js","sources":["../src/portal.ts"],"sourcesContent":["/**\n * Portable portal surface hook — renderer-neutral overlay root management.\n *\n * Manages the lifecycle of a portal RootSurface (create/update/destroy)\n * using the SurfaceAdapter stored on the current SurfaceContext.\n *\n * The actual VDOM mounting of children is left to the renderer-specific\n * Portal component (e.g., @number10/jsx-phaser's Portal.tsx), which calls\n * this hook and renders into `surface.root`.\n *\n * @example\n * ```typescript\n * // In a Phaser Portal component:\n * import { usePortalSurface } from '@number10/jsx-core'\n *\n * function Portal(props) {\n *   const { surface, error } = usePortalSurface({\n *     depth: props.depth ?? 1000,\n *     id: props.id,\n *   })\n *\n *   if (error) return null\n *   if (!surface) return null\n *\n *   // Mount children into surface.root (renderer-specific)\n *   // ...\n * }\n * ```\n */\n\nimport { useEffect, useRef, useState, useSurface } from './hooks'\nimport type { RootSurface, SurfaceAdapter, SurfaceContext } from './host-adapter'\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Options for usePortalSurface */\nexport interface UsePortalSurfaceOptions {\n  /** Z-depth for the portal (higher = on top of others) */\n  depth?: number\n  /** Optional unique portal ID */\n  id?: string\n  /**\n   * Block input events from passing through the portal area.\n   * The renderer adapter is responsible for implementing the actual\n   * event blocking (e.g., gesture blocker containers in Phaser).\n   */\n  blockEvents?: boolean\n}\n\n/** Result of usePortalSurface */\nexport interface UsePortalSurfaceResult {\n  /**\n   * The portal RootSurface, or null if not yet created.\n   * Renderers mount children into `surface.root`.\n   */\n  surface: RootSurface | null\n  /**\n   * Error message if portal creation failed.\n   * Component should render nothing when this is set.\n   */\n  error: string | null\n  /**\n   * Update the portal's depth or viewport dimensions.\n   * Call when depth prop changes or on viewport resize.\n   */\n  update: (updates: { depth?: number; width?: number; height?: number }) => void\n  /**\n   * Explicitly destroy the portal surface.\n   * Automatically called on unmount via useEffect cleanup.\n   */\n  destroy: () => void\n  /**\n   * Renderer-bound VDOM operations for mounting children.\n   * Portable components use this instead of importing renderer-specific\n   * mount/patchVNode/unmount to avoid multi-renderer conflicts.\n   */\n  vdom: SurfaceContext['vdom']\n}\n\n// ---------------------------------------------------------------------------\n// usePortalSurface\n// ---------------------------------------------------------------------------\n\n/**\n * Portable hook that creates and manages a portal RootSurface.\n *\n * Uses the SurfaceAdapter from the current SurfaceContext to create\n * a portal surface as a child of the parent surface. The hook handles\n * lifecycle: create on mount, update on option changes, destroy on unmount.\n *\n * @param options - Portal configuration\n * @returns Portal surface handle with update/destroy methods\n *\n * @migration(audit:surface-access) Phase 6B — portable portal surface lifecycle.\n *   Replaces manual createRoot/destroyRoot in renderer-specific Portal components.\n */\nexport function usePortalSurface(options: UsePortalSurfaceOptions = {}): UsePortalSurfaceResult {\n  const surfaceContext = useSurface()\n  const adapter: SurfaceAdapter | undefined = surfaceContext?.adapter\n  const parentSurface: RootSurface | undefined =\n    surfaceContext?.rootSurface ??\n    (surfaceContext?.raw ? findParentSurface(adapter, surfaceContext.raw) : undefined)\n\n  const [portalSurface, setPortalSurface] = useState<RootSurface | null>(null)\n  const portalRef = useRef<RootSurface | null>(null)\n  const [error, setError] = useState<string | null>(null)\n  const depthRef = useRef(options.depth ?? 1000)\n\n  // Track whether we've mounted to avoid double-init\n  const mountedRef = useRef(false)\n\n  // Create portal surface on mount\n  useEffect(() => {\n    if (!adapter) {\n      setError('No SurfaceAdapter available — cannot create portal')\n      return\n    }\n\n    if (!parentSurface) {\n      setError('No parent RootSurface found — cannot create portal')\n      return\n    }\n\n    if (mountedRef.current) return\n    mountedRef.current = true\n\n    const depth = options.depth ?? 1000\n    depthRef.current = depth\n\n    try {\n      const created = adapter.createRoot({\n        kind: 'portal',\n        parent: parentSurface,\n        zIndex: depth,\n        width: surfaceContext?.viewport.width ?? 0,\n        height: surfaceContext?.viewport.height ?? 0,\n        ...(options.id ? { id: options.id } : {}),\n      })\n\n      portalRef.current = created\n      setPortalSurface(created)\n      setError(null)\n    } catch (e) {\n      setError(`Failed to create portal surface: ${(e as Error).message}`)\n    }\n\n    return () => {\n      mountedRef.current = false\n      const current = portalRef.current\n      if (current) {\n        portalRef.current = null\n        setPortalSurface(null)\n        try {\n          adapter.destroyRoot(current)\n        } catch {\n          // Surface may already be destroyed by scene shutdown\n        }\n      }\n    }\n    // Only run on mount\n  }, [])\n\n  const update = (updates: { depth?: number; width?: number; height?: number }) => {\n    const current = portalRef.current\n    if (!current || !adapter) return\n\n    if (updates.depth !== undefined) depthRef.current = updates.depth\n\n    adapter.updateRoot(current, {\n      ...(updates.depth !== undefined ? { zIndex: updates.depth } : {}),\n      ...(updates.width !== undefined ? { width: updates.width } : {}),\n      ...(updates.height !== undefined ? { height: updates.height } : {}),\n    })\n  }\n\n  const destroy = () => {\n    const current = portalRef.current\n    if (current && adapter) {\n      portalRef.current = null\n      setPortalSurface(null)\n      try {\n        adapter.destroyRoot(current)\n      } catch {\n        // Surface may already be destroyed\n      }\n      mountedRef.current = false\n    }\n  }\n\n  return {\n    surface: portalSurface,\n    error,\n    update,\n    destroy,\n    vdom: surfaceContext?.vdom,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Find the parent RootSurface for a given renderer-native target.\n * Scans the adapter's registered surfaces for one whose raw target matches.\n */\nfunction findParentSurface(\n  adapter: SurfaceAdapter | undefined,\n  target: unknown\n): RootSurface | undefined {\n  if (!adapter || !adapter.getRootByTarget) return undefined\n  return adapter.getRootByTarget(target)\n}\n"],"names":[],"mappings":";AAkGO,SAAS,iBAAiB,UAAmC,IAA4B;AAC9F,QAAM,iBAAiB,WAAA;AACvB,QAAM,UAAsC,gBAAgB;AAC5D,QAAM,gBACJ,gBAAgB,gBACf,gBAAgB,MAAM,kBAAkB,SAAS,eAAe,GAAG,IAAI;AAE1E,QAAM,CAAC,eAAe,gBAAgB,IAAI,SAA6B,IAAI;AAC3E,QAAM,YAAY,OAA2B,IAAI;AACjD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAwB,IAAI;AACtD,QAAM,WAAW,OAAO,QAAQ,SAAS,GAAI;AAG7C,QAAM,aAAa,OAAO,KAAK;AAG/B,YAAU,MAAM;AACd,QAAI,CAAC,SAAS;AACZ,eAAS,oDAAoD;AAC7D;AAAA,IACF;AAEA,QAAI,CAAC,eAAe;AAClB,eAAS,oDAAoD;AAC7D;AAAA,IACF;AAEA,QAAI,WAAW,QAAS;AACxB,eAAW,UAAU;AAErB,UAAM,QAAQ,QAAQ,SAAS;AAC/B,aAAS,UAAU;AAEnB,QAAI;AACF,YAAM,UAAU,QAAQ,WAAW;AAAA,QACjC,MAAM;AAAA,QACN,QAAQ;AAAA,QACR,QAAQ;AAAA,QACR,OAAO,gBAAgB,SAAS,SAAS;AAAA,QACzC,QAAQ,gBAAgB,SAAS,UAAU;AAAA,QAC3C,GAAI,QAAQ,KAAK,EAAE,IAAI,QAAQ,GAAA,IAAO,CAAA;AAAA,MAAC,CACxC;AAED,gBAAU,UAAU;AACpB,uBAAiB,OAAO;AACxB,eAAS,IAAI;AAAA,IACf,SAAS,GAAG;AACV,eAAS,oCAAqC,EAAY,OAAO,EAAE;AAAA,IACrE;AAEA,WAAO,MAAM;AACX,iBAAW,UAAU;AACrB,YAAM,UAAU,UAAU;AAC1B,UAAI,SAAS;AACX,kBAAU,UAAU;AACpB,yBAAiB,IAAI;AACrB,YAAI;AACF,kBAAQ,YAAY,OAAO;AAAA,QAC7B,QAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF;AAAA,EAEF,GAAG,CAAA,CAAE;AAEL,QAAM,SAAS,CAAC,YAAiE;AAC/E,UAAM,UAAU,UAAU;AAC1B,QAAI,CAAC,WAAW,CAAC,QAAS;AAE1B,QAAI,QAAQ,UAAU,OAAW,UAAS,UAAU,QAAQ;AAE5D,YAAQ,WAAW,SAAS;AAAA,MAC1B,GAAI,QAAQ,UAAU,SAAY,EAAE,QAAQ,QAAQ,MAAA,IAAU,CAAA;AAAA,MAC9D,GAAI,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,MAAA,IAAU,CAAA;AAAA,MAC7D,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,WAAW,CAAA;AAAA,IAAC,CAClE;AAAA,EACH;AAEA,QAAM,UAAU,MAAM;AACpB,UAAM,UAAU,UAAU;AAC1B,QAAI,WAAW,SAAS;AACtB,gBAAU,UAAU;AACpB,uBAAiB,IAAI;AACrB,UAAI;AACF,gBAAQ,YAAY,OAAO;AAAA,MAC7B,QAAQ;AAAA,MAER;AACA,iBAAW,UAAU;AAAA,IACvB;AAAA,EACF;AAEA,SAAO;AAAA,IACL,SAAS;AAAA,IACT;AAAA,IACA;AAAA,IACA;AAAA,IACA,MAAM,gBAAgB;AAAA,EAAA;AAE1B;AAUA,SAAS,kBACP,SACA,QACyB;AACzB,MAAI,CAAC,WAAW,CAAC,QAAQ,gBAAiB,QAAO;AACjD,SAAO,QAAQ,gBAAgB,MAAM;AACvC;"}

package/dist/primitive-contracts.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const PRIMITIVE_NODES = {
+  View: "view",
+  Text: "text",
+  Image: "image",
+  Sprite: "sprite",
+  VectorDrawContent: "vectorDraw",
+  NineSlice: "nineslice"
+};
+exports.PRIMITIVE_NODES = PRIMITIVE_NODES;
+//# sourceMappingURL=primitive-contracts.cjs.map

package/dist/primitive-contracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive-contracts.cjs","sources":["../src/primitive-contracts.ts"],"sourcesContent":["/**\n * Portable Primitive Contracts — renderer-neutral prop interfaces for\n * View, Text, Image, and Sprite primitives.\n *\n * These contracts define the MINIMAL prop set that every renderer must\n * support. Each renderer package extends these with renderer-specific\n * props (e.g., Phaser adds PhaserProps and onReady).\n *\n * Portable Components MUST only import from this file and other Core modules.\n * They MUST NOT import from renderer-specific packages or Phaser directly.\n *\n * @migration(audit:scene-portal-mount) Phase 4B — defined in @number10/jsx-core.\n *   Renderer implementations live in the renderer package.\n */\n\nimport type {\n  BackgroundProps,\n  GestureProps,\n  LayoutProps,\n  SizeValue,\n  TransformProps,\n} from './core-props'\nimport type { PropsContainerExtension, PropsDefaultExtension } from './types'\n\n// ---------------------------------------------------------------------------\n// Primitive Host-Node Names\n// ---------------------------------------------------------------------------\n\n/**\n * Stable host-node type names for renderer-neutral primitives.\n *\n * These are the `type` values passed to `HostAdapter.create()` and used\n * in JSX as lowercase tags (`<view/>`, `<text/>`, ...).\n * Each renderer registers HostDescriptors for these names.\n *\n * Portable components MUST NOT use these directly in JSX.\n * They use the uppercase wrappers from `@number10/jsx-components/primitives`.\n */\nexport const PRIMITIVE_NODES = {\n  View: 'view',\n  Text: 'text',\n  Image: 'image',\n  Sprite: 'sprite',\n  VectorDrawContent: 'vectorDraw',\n  NineSlice: 'nineslice',\n} as const\n\n/** Host-node type names for renderer-neutral primitives */\nexport type PrimitiveNodeType = (typeof PRIMITIVE_NODES)[keyof typeof PRIMITIVE_NODES]\n\n// ---------------------------------------------------------------------------\n// View — the fundamental layout container\n// ---------------------------------------------------------------------------\n\n/**\n * Portable props for the View primitive.\n * Every renderer must support: layout, transform, background styling, and alpha.\n */\nexport interface ViewPrimitiveProps\n  extends TransformProps, LayoutProps, BackgroundProps, GestureProps {\n  /**\n   * Alpha transparency of the element.\n   * - 0: Fully transparent\n   * - 1: Fully opaque (default)\n   */\n  alpha?: number\n}\n\n/**\n * Complete View props including JSX extensions.\n * The generic parameter allows renderers to specify their native node type for Refs.\n *\n * @typeParam TNode - The renderer's native node type (e.g., Phaser.GameObjects.Container)\n */\nexport interface ViewPrimitivePropsComplete<TNode = unknown>\n  extends ViewPrimitiveProps, PropsDefaultExtension<TNode>, PropsContainerExtension {}\n\n// ---------------------------------------------------------------------------\n// Text — text rendering\n// ---------------------------------------------------------------------------\n\n/**\n * Portable text style — renderer-neutral text formatting.\n * Each renderer maps this to its native text style type.\n */\nexport interface PortableTextStyle {\n  fontSize?: string | number\n  fontFamily?: string\n  fontStyle?: string\n  fontWeight?: string | number\n  color?: string | number\n  backgroundColor?: string | number\n  align?: 'left' | 'center' | 'right' | 'justify'\n  lineHeight?: number\n  shadow?:\n    | {\n        color?: string | number\n        blur?: number\n        offsetX?: number\n        offsetY?: number\n        alpha?: number\n        fill?: boolean\n        stroke?: boolean\n      }\n    | undefined\n}\n\n/**\n * Portable props for the Text primitive.\n */\nexport interface TextPrimitiveProps extends TransformProps, LayoutProps, GestureProps {\n  /** The text content to display */\n  text: string | undefined\n  /** Maximum width for text wrapping */\n  maxWidth?: SizeValue\n  /** Portable text style — renderer maps to native style. Named 'style' for compat with Phaser's TextProps. */\n  style?: PortableTextStyle | undefined\n}\n\n/**\n * Complete Text props including JSX extensions.\n */\nexport interface TextPrimitivePropsComplete<TNode = unknown>\n  extends TextPrimitiveProps, PropsDefaultExtension<TNode>, PropsContainerExtension {}\n\n// ---------------------------------------------------------------------------\n// Image — texture-backed image display\n// ---------------------------------------------------------------------------\n\n/**\n * Portable props for the Image primitive.\n */\nexport interface ImagePrimitiveProps extends TransformProps, LayoutProps {\n  /** Texture key or URL */\n  texture: string\n  /** Optional tint color */\n  tint?: number | undefined\n  /** Optional frame from texture atlas */\n  frame?: string | undefined\n  /**\n   * Optional explicit source region within the texture/frame.\n   *\n   * When set, the image only renders this sub-rectangle of the source\n   * texture. Coordinates are relative to the frame origin (if `frame`\n   * is specified) or the texture origin otherwise.\n   *\n   * Enables portable NineSlice: each slice cell is an `<Image>` with\n   * its own `sourceRect` computed from the frame geometry.\n   */\n  sourceRect?: { x: number; y: number; w: number; h: number } | undefined\n  /** Display width — scaled rendering size (defaults to texture width) */\n  displayWidth?: number | undefined\n  /** Display height — scaled rendering size (defaults to texture height) */\n  displayHeight?: number | undefined\n  /**\n   * How image fits within displayWidth/displayHeight bounds.\n   * - 'fill': Stretch to fill (default, may distort aspect ratio)\n   * - 'contain': Scale to fit within bounds, preserve aspect ratio\n   * - 'cover': Scale to cover bounds, preserve aspect ratio (may crop)\n   */\n  fit?: 'fill' | 'contain' | 'cover' | undefined\n  /** Origin X anchor point (0-1, default 0.5 for headless, 0 for layout) */\n  originX?: number | undefined\n  /** Origin Y anchor point (0-1, default 0.5 for headless, 0 for layout) */\n  originY?: number | undefined\n}\n\n/**\n * Complete Image props including JSX extensions.\n */\nexport interface ImagePrimitivePropsComplete<TNode = unknown>\n  extends ImagePrimitiveProps, PropsDefaultExtension<TNode> {}\n\n// ---------------------------------------------------------------------------\n// Sprite — animated texture-backed display\n// ---------------------------------------------------------------------------\n\n/**\n * Portable props for the Sprite primitive.\n */\nexport interface SpritePrimitiveProps extends TransformProps, LayoutProps {\n  /** Texture key or URL */\n  texture: string\n  /** Optional tint color */\n  tint?: number\n  /** Optional frame from texture atlas */\n  frame?: string\n  /** Optional animation key to play on mount */\n  anim?: string\n}\n\n/**\n * Complete Sprite props including JSX extensions.\n */\nexport interface SpritePrimitivePropsComplete<TNode = unknown>\n  extends SpritePrimitiveProps, PropsDefaultExtension<TNode> {}\n\n// ---------------------------------------------------------------------------\n// Component Import Style — the contract for portable components\n// ---------------------------------------------------------------------------\n\n/**\n * Portable Components MUST follow this import style:\n *\n * ```typescript\n * // ✅ CORRECT — only Core imports\n * import type { ViewPrimitiveProps, TextPrimitiveProps } from '@number10/jsx-core'\n * import { useState, useEffect, useTheme } from '@number10/jsx-core'\n * import type { LayoutProps, TransformProps } from '@number10/jsx-core'\n * import type { VNode, Ref } from '@number10/jsx-core'\n *\n * // ✅ CORRECT — renderer provides the actual primitives\n * // (imported by the app, passed via JSX or context, not imported in the component)\n *\n * // ❌ WRONG — Phaser-specific imports in portable components\n * // import type { PhaserProps } from '@number10/jsx-phaser'\n * // import { useScene } from '@number10/jsx-phaser'\n * // import type * as Phaser from 'phaser'\n * ```\n */\n\n// ---------------------------------------------------------------------------\n// Optional Primitive Capabilities\n// ---------------------------------------------------------------------------\n\n/**\n * The following primitives are OPTIONAL capabilities. A renderer MAY support\n * them. Portable components SHOULD NOT depend on them unless the capability\n * is explicitly checked via `SurfaceContext.capabilities`.\n *\n * | Primitive   | Capability Key   | Type in PRIMITIVE_NODES | Notes |\n * |-------------|-----------------|-------------------------|-------|\n * | NineSlice   | `nineslice`     | `'nineslice'`           | First-class primitive in PRIMITIVE_NODES; single-node native 9-slice |\n * | TileSprite  | `tilesprite`    | —                       | Tiled texture background |\n * | VectorDraw  | `drawing`       | `'vectorDraw'`          | Portable imperative drawing API |\n * | Particles   | `particles`     | —                       | Renderer-native particle system |\n *\n * Portable components that need these should:\n * 1. Check `SurfaceContext.capabilities.has('nineslice')` before use\n * 2. Provide a fallback (e.g., use View+Image instead of NineSlice)\n * 3. OR accept them as optional child/overlay via props\n */\n\nexport {\n  computeSourceSlices,\n  computeTargetXs,\n  computeTargetYs,\n  deriveTargetRects,\n} from './nineslice-contract'\nexport type {\n  NineSlicePrimitiveProps,\n  NineSlicePrimitivePropsComplete,\n  SliceRect,\n} from './nineslice-contract'\n\nexport type { VectorDrawContentPrimitivePropsComplete } from './vector-draw-context'\n"],"names":[],"mappings":";;AAsCO,MAAM,kBAAkB;AAAA,EAC7B,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,mBAAmB;AAAA,EACnB,WAAW;AACb;;"}