fix: support private child elements in browser esm

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: chillenious

docs/PACKAGING_ARCHITECTURE.md

@@ -95,8 +95,18 @@ The shared browser ESM config in `tools/vite/element-browser.config.ts` runs fro
 the element package directory. It discovers existing `src/delivery`,
 `src/author`, `src/print`, and `src/controller` entries, writes them to
 `dist/browser`, and only externalizes bare imports listed in
-`tools/vite/browser-esm-policy.json`. It also strips package-time custom element
-registration because players own tag registration.
+`tools/vite/browser-esm-policy.json`. It injects the owning package name/version
+as build-time constants so browser artifacts can derive deterministic,
+version-scoped private child custom element tags.
+
+Browser ESM keeps the same registration boundary as the runtime contract:
+players own authored top-level PIE tag registration, while an element package
+owns the package-private child custom elements it renders internally. This is
+why private child definitions such as EBSR's multiple-choice parts are kept in
+the browser artifact instead of being discovered by `pie-players` at runtime.
+Whether or not EBSR's "two multiple-choice children" design is the ideal
+architecture, it is the behavior that existing IIFE bundles have shipped for a
+long time, so browser ESM must support it for compatibility.
 
 ### Browser ESM CommonJS Interop
 

docs/PIE_ELEMENT_CONTRACT.md

@@ -35,7 +35,23 @@ When a helper is exported, its name and behavior are public API. Do not rename o
 
 ### Custom Element Runtime
 
-Published element view modules export custom element classes. They must not register tags at package import time. Runtime registration belongs to the player or host.
+Published element view modules export custom element classes. They must not
+register their authored top-level PIE tag at package import time. Runtime
+registration of authored item tags belongs to the player or host.
+
+If a package renders private child custom elements inside its own implementation,
+the package's browser artifact must define those private child tags itself before
+the first render depends on them. Private child tags are not authored content
+dependencies and players must not discover them from package dependencies, DOM
+snippets, or element-specific knowledge.
+
+Private child tag names are global custom element names, so packages must scope
+them by the owning package version (for example with a `--version-<encoded>`
+suffix), use the same scoped name for registration and rendering, and keep
+registration idempotent with `customElements.get(...)` guards. This preserves
+side-by-side loading of multiple package versions and mirrors the IIFE behavior
+where private child implementations are resolved from the owning package's
+dependency tree at build time.
 
 Players set data via properties, not attributes:
 

packages/elements-react/complex-rubric/src/author/index.ts

@@ -17,10 +17,14 @@ import debug from 'debug';
 import { defaults } from '@pie-element/shared-lodash';
 import Main from './main.js';
 import sensibleDefaults from './defaults.js';
+import {
+  COMPLEX_RUBRIC_MULTI_TRAIT_CONFIGURE_TAG,
+  COMPLEX_RUBRIC_SIMPLE_CONFIGURE_TAG,
+} from '../private-tags.js';
 
 const MODEL_UPDATED = ModelUpdatedEvent.TYPE;
-const RUBRIC_TAG_NAME = 'rubric-configure';
-const MULTI_TRAIT_RUBRIC_TAG_NAME = 'multi-trait-rubric-configure';
+const RUBRIC_TAG_NAME = COMPLEX_RUBRIC_SIMPLE_CONFIGURE_TAG;
+const MULTI_TRAIT_RUBRIC_TAG_NAME = COMPLEX_RUBRIC_MULTI_TRAIT_CONFIGURE_TAG;
 
 class ComplexSimpleRubricConfigure extends RubricConfigure {}
 
@@ -159,8 +163,10 @@ export default class ComplexRubricConfigureElement extends HTMLElement {
     let element = React.createElement(Main, {
       model: this._model,
       configuration: this._configuration,
+      multiTraitRubricTagName: MULTI_TRAIT_RUBRIC_TAG_NAME,
       onModelChanged: this.onModelChanged,
       onConfigurationChanged: this.onConfigurationChanged,
+      simpleRubricTagName: RUBRIC_TAG_NAME,
       canUpdateModel: this.canUpdateModel
     });
 

packages/elements-react/complex-rubric/src/author/main.tsx

@@ -17,6 +17,10 @@ import RadioGroup from '@mui/material/RadioGroup';
 import FormControlLabel from '@mui/material/FormControlLabel';
 import { styled } from '@mui/material/styles';
 import { color } from '@pie-lib/render-ui';
+import {
+  COMPLEX_RUBRIC_MULTI_TRAIT_CONFIGURE_TAG,
+  COMPLEX_RUBRIC_SIMPLE_CONFIGURE_TAG,
+} from '../private-tags.js';
 
 const StyledFormControlLabel: any = styled(FormControlLabel)({
   '&.MuiFormControlLabel-root': {
@@ -45,9 +49,11 @@ export class Main extends React.Component {
   static propTypes = {
     canUpdateModel: PropTypes.bool,
     configuration: PropTypes.object,
+    multiTraitRubricTagName: PropTypes.string,
     model: PropTypes.object,
     onModelChanged: PropTypes.func,
     onConfigurationChanged: PropTypes.func,
+    simpleRubricTagName: PropTypes.string,
   };
 
   onModelChanged: any = (model) => {
@@ -64,7 +70,15 @@ export class Main extends React.Component {
   };
 
   render() {
-    const { model, configuration, canUpdateModel } = this.props;
+    const {
+      model,
+      configuration,
+      canUpdateModel,
+      multiTraitRubricTagName = COMPLEX_RUBRIC_MULTI_TRAIT_CONFIGURE_TAG,
+      simpleRubricTagName = COMPLEX_RUBRIC_SIMPLE_CONFIGURE_TAG,
+    } = this.props;
+    const MultiTraitRubricConfigureElement = multiTraitRubricTagName;
+    const SimpleRubricConfigureElement = simpleRubricTagName;
 
     const { extraCSSRules, rubrics = {} } = model || {};
     let { rubricType } = model;
@@ -89,7 +103,7 @@ export class Main extends React.Component {
         case RUBRIC_TYPES.SIMPLE_RUBRIC:
         default:
           rubricTag = (
-            <rubric-configure
+            <SimpleRubricConfigureElement
               id="simpleRubric"
               key="simple-rubric"
               ref={(ref) => {
@@ -105,7 +119,7 @@ export class Main extends React.Component {
 
         case RUBRIC_TYPES.MULTI_TRAIT_RUBRIC:
           rubricTag = (
-            <multi-trait-rubric-configure
+            <MultiTraitRubricConfigureElement
               id="multiTraitRubric"
               key="multi-trait-rubric"
               ref={(ref) => {
@@ -122,7 +136,7 @@ export class Main extends React.Component {
 
         case RUBRIC_TYPES.RUBRICLESS:
           rubricTag = (
-            <rubric-configure
+            <SimpleRubricConfigureElement
               id="rubricless"
               key="rubricless"
               ref={(ref) => {

packages/elements-react/complex-rubric/src/delivery/index.ts

@@ -11,9 +11,10 @@
 import Rubric from '@pie-element/rubric';
 import MultiTraitRubric from '@pie-element/multi-trait-rubric';
 import { RUBRIC_TYPES } from '@pie-lib/rubric';
+import { COMPLEX_RUBRIC_MULTI_TRAIT_TAG, COMPLEX_RUBRIC_SIMPLE_TAG } from '../private-tags.js';
 
-const RUBRIC_TAG_NAME = 'complex-rubric-simple';
-const MULTI_TRAIT_RUBRIC_TAG_NAME = 'complex-rubric-multi-trait';
+const RUBRIC_TAG_NAME = COMPLEX_RUBRIC_SIMPLE_TAG;
+const MULTI_TRAIT_RUBRIC_TAG_NAME = COMPLEX_RUBRIC_MULTI_TRAIT_TAG;
 
 class ComplexRubricSimple extends Rubric {}
 

packages/elements-react/complex-rubric/src/print/index.ts

@@ -13,9 +13,10 @@ import Rubric from '@pie-element/rubric';
 // here it is actually using multi-trait-rubric/src/index.js, instead of using multi-trait-rubric/src/print.js
 import MultiTraitRubric from '@pie-element/multi-trait-rubric';
 import { RUBRIC_TYPES } from '@pie-lib/rubric';
+import { COMPLEX_RUBRIC_MULTI_TRAIT_TAG, COMPLEX_RUBRIC_SIMPLE_TAG } from '../private-tags.js';
 
-const RUBRIC_TAG_NAME = 'complex-rubric-simple';
-const MULTI_TRAIT_RUBRIC_TAG_NAME = 'complex-rubric-multi-trait';
+const RUBRIC_TAG_NAME = COMPLEX_RUBRIC_SIMPLE_TAG;
+const MULTI_TRAIT_RUBRIC_TAG_NAME = COMPLEX_RUBRIC_MULTI_TRAIT_TAG;
 
 class ComplexRubricSimple extends Rubric {}
 class ComplexRubricMultiTrait extends MultiTraitRubric {}

packages/elements-react/complex-rubric/src/private-tags.ts

@@ -0,0 +1,20 @@
+declare const __PIE_PACKAGE_VERSION__: string | undefined;
+
+const encodeVersionForTag = (version: string): string =>
+  version
+    .trim()
+    .toLowerCase()
+    .replace(/[.+]/g, '-')
+    .replace(/[^0-9A-Za-z-]/g, '-')
+    .replace(/-{2,}/g, '-');
+
+const ownerVersion =
+  typeof __PIE_PACKAGE_VERSION__ === 'string' && __PIE_PACKAGE_VERSION__.trim()
+    ? __PIE_PACKAGE_VERSION__
+    : 'local';
+const ownerVersionSuffix = `--version-${encodeVersionForTag(ownerVersion)}`;
+
+export const COMPLEX_RUBRIC_SIMPLE_TAG = `complex-rubric-simple${ownerVersionSuffix}`;
+export const COMPLEX_RUBRIC_MULTI_TRAIT_TAG = `complex-rubric-multi-trait${ownerVersionSuffix}`;
+export const COMPLEX_RUBRIC_SIMPLE_CONFIGURE_TAG = `rubric-configure${ownerVersionSuffix}`;
+export const COMPLEX_RUBRIC_MULTI_TRAIT_CONFIGURE_TAG = `multi-trait-rubric-configure${ownerVersionSuffix}`;

packages/elements-react/complex-rubric/vite.config.iife.ts

@@ -1,8 +1,13 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import react from '@vitejs/plugin-react';
 import { defineConfig } from 'vite';
 
+const packageJson = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8')) as {
+  name?: string;
+  version?: string;
+};
+
 const resolveWorkspaceEntry = (baseDir: string): string | null => {
   const candidates = ['index.ts', 'index.tsx', 'index.js', 'index.jsx'];
   for (const candidate of candidates) {
@@ -55,6 +60,8 @@ export default defineConfig({
     react(),
   ],
   define: {
+    __PIE_PACKAGE_NAME__: JSON.stringify(packageJson.name ?? ''),
+    __PIE_PACKAGE_VERSION__: JSON.stringify(packageJson.version ?? 'local'),
     'process.env.NODE_ENV': JSON.stringify('production'),
   },
   build: {

packages/elements-react/complex-rubric/vite.config.ts

@@ -1,7 +1,13 @@
+import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import react from '@vitejs/plugin-react';
 import { defineConfig } from 'vite';
 
+const packageJson = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8')) as {
+  name?: string;
+  version?: string;
+};
+
 export default defineConfig(({ mode, command }) => {
   // Demo mode: serve the docs/demo directory
   if (mode === 'demo' && command === 'serve') {
@@ -14,6 +20,10 @@ export default defineConfig(({ mode, command }) => {
   // Build mode: build the library
   return {
   plugins: [react()],
+  define: {
+    __PIE_PACKAGE_NAME__: JSON.stringify(packageJson.name ?? ''),
+    __PIE_PACKAGE_VERSION__: JSON.stringify(packageJson.version ?? 'local'),
+  },
   build: {
     lib: {
       entry: {

packages/elements-react/ebsr/src/author/index.ts

@@ -14,11 +14,12 @@ import { ModelUpdatedEvent } from '@pie-element/shared-configure-events';
 import MultipleChoiceConfigure from '@pie-element/multiple-choice/author';
 import { defaults } from '@pie-element/shared-lodash';
 import Main from './main.js';
+import { EBSR_MULTIPLE_CHOICE_CONFIGURE_TAG } from '../private-tags.js';
 
 import sensibleDefaults from './defaults.js';
 
 const MODEL_UPDATED = ModelUpdatedEvent.TYPE;
-const MC_TAG_NAME = 'ebsr-multiple-choice-configure';
+const MC_TAG_NAME = EBSR_MULTIPLE_CHOICE_CONFIGURE_TAG;
 
 class EbsrMCConfigure extends MultipleChoiceConfigure {}
 const defineMultipleChoice = () => {
@@ -165,6 +166,7 @@ export default class EbsrConfigure extends HTMLElement {
     let element = React.createElement(Main, {
       model: this._model,
       configuration: this._configuration,
+      multipleChoiceTagName: MC_TAG_NAME,
       onModelChanged: this.onModelChanged,
       onConfigurationChanged: this.onConfigurationChanged,
     });