chore: add changeset-driven publish workflow and mc updates

Add reusable scripts/docs for targeted changeset-based publishing while carrying forward the latest mc-populated-blank implementation updates in this branch.

Made-with: Cursor

Author: chillenious

.github/workflows/release.yml

@@ -223,7 +223,7 @@ jobs:
         id: changesets
         uses: changesets/action@v1
         with:
-          publish: bun run release
+          publish: bun run release:publish
           version: bun run version
           title: 'chore(release): version packages [skip-heavy-ci]'
           commit: 'chore(release): version packages'

README.md

@@ -117,6 +117,29 @@ If a publish fails after the version PR was already merged, rerun the Release wo
 
 This is intended for recovery/rerun scenarios only.
 
+### Targeted Package Release (Changesets)
+
+To release one or more specific packages, create a changeset scoped to those packages:
+
+```bash
+bun run changeset:plan -- --packages @pie-element/mc-populated-blank --type patch --summary "Fix CQT parity for VIC/SEL VIC variants"
+```
+
+For multiple packages:
+
+```bash
+bun run changeset:plan -- --packages @pie-element/mc-populated-blank,@pie-element/simple-cloze --type minor --summary "Add Svelte release updates"
+```
+
+Then run the normal Changesets flow:
+
+```bash
+# 1) Commit and merge PR with the generated .changeset file
+# 2) Let CI create/merge the version PR
+# 3) CI publishes via the same command used manually:
+bun run release:publish
+```
+
 ### Maintainer Commands
 
 `bun cli upstream:sync` - (Maintainers only) Syncs packages from the upstream pie-elements project. Requires pie-elements and pie-lib checked out as sibling directories. Analyzes the current state of those projects and copies over what is ready for ESM packaging, including rewrites and restructuring to fit the new project layout.
@@ -126,21 +149,27 @@ This is intended for recovery/rerun scenarios only.
 PIE elements include print views for generating paper-based assessments and answer keys. Two complementary players serve different use cases:
 
 ### Element-Level Print Player (This Project)
+
 For development and testing of individual elements:
+
 ```html
 <pie-element-player view="print" element-name="multiple-choice" role="student"></pie-element-player>
 ```
+
 - **Package:** `@pie-element/element-player`
 - **Use for:** Element development, testing, documentation, and optional composable embedding
 - **Location:** `packages/element-player/src/players/PieElementPlayer.svelte`
 
 For most production app flows, prefer the standard upstream player stacks in `../pie-elements` and `../pie-players`.
 
 ### Item-Level Print Player (pie-players)
+
 For production rendering of complete assessment items:
+
 ```html
 <pie-print config={{ item: {...}, options: { mode: 'student' } }}></pie-print>
 ```
+
 - **Package:** `@pie-player/print` (in pie-players repository)
 - **Use for:** Production apps, multi-element items, markup-driven rendering
 - **Location:** `../pie-players/packages/print-player`

package.json

@@ -39,8 +39,11 @@
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
     "changeset": "changeset",
+    "changeset:plan": "node ./scripts/create-package-changeset.mjs",
     "version": "changeset version",
-    "release": "bun run build && bun run cli verify:controllers && node ./scripts/changeset-publish-resolved-workspaces.mjs",
+    "release": "bun run release:publish",
+    "release:publish": "bun run build && bun run cli verify:controllers && node ./scripts/changeset-publish-resolved-workspaces.mjs",
+    "release:manual": "bun run release:publish",
     "release:label": "node ./scripts/create-release-label.mjs",
     "release:label:push": "node ./scripts/create-release-label.mjs --push",
     "clean": "turbo run clean && rm -rf node_modules",

packages/elements-svelte/mc-populated-blank/CONTRACT-CHECKLIST.md

@@ -1,20 +1,128 @@
 # @pie-element/mc-populated-blank
 
-Svelte 5 PIE element: the learner picks a **multiple-choice** option and that choice **fills a blank** inside an HTML **template**.
+Svelte 5 PIE element where the learner picks a **multiple-choice** option and that choice **fills a blank** in a sentence/template.
+
+This element is the PIE counterpart for Star Learnosity CQT "populated blank" interactions. The CQT family had several published `custom_type` flavors, but they are all variants of the same base interaction:
+
+- one selected choice
+- one correctness key
+- selected choice rendered into a blank target
+- optional audio/transcript support
+
+## What the original CQT flavors mean
+
+The historical Learnosity CQT names mostly describe layout/stimulus differences, not different scoring logic:
+
+- `sel_vic`: sentence-style vocabulary in context, with audio/transcript support
+- `sr-vic`: sentence-style vocabulary in context, typically no audio button
+- `sel_r1-g_plusggg`: lead token before blank (`before_cloze_1`) plus choice set
+- `sel_r1-_gplusggg`: blank with a shorter/token-focused stem arrangement
+- `sel_r1-_plusggg`: audio + choices only (no blank; modeled as audio-only mode)
+- `sel_r1-gg_plusggg`: token-sequence variant with larger glyph-like tokens
+- `sel_r1-_ggplusggg`: blank appears before trailing tokens (`after_cloze_*`)
+- `sel_r1-s3_plusggg`: stimulus-heavy variant (often image/sentence block + blank + choices)
+
+The shared behavior across these flavors is now represented by one element with configuration, instead of one element per flavor.
+
+## Flavor to model mapping (quick defaults)
+
+Use this as a practical starting point when mapping Learnosity CQT payloads into `mc-populated-blank` models.
+
+| Learnosity `custom_type` | Typical layout meaning | Suggested `interactionMode` | Suggested `choiceMode` | Template hint |
+| --- | --- | --- | --- | --- |
+| `sel_vic` | sentence cloze with audio/transcript | `populate_blank` | `text` | `<p>{before} {{blank}} {after}</p>` |
+| `sr-vic` | sentence cloze without listen button | `populate_blank` | `text` | `<p>{before} {{blank}} {after}</p>` |
+| `sel_r1-g_plusggg` | lead token before blank | `populate_blank` | `text` | `<p>{before_cloze_1} {{blank}}</p>` |
+| `sel_r1-_gplusggg` | short stem + blank | `populate_blank` | `text` | `<p>{before/after segments around {{blank}}}</p>` |
+| `sel_r1-_plusggg` | audio + choices only (no blank) | `audio_mc_only` | `text` | no blank token in template |
+| `sel_r1-gg_plusggg` | token-sequence style before blank | `populate_blank` | `text` | `<p>{before_1}{before_2} {{blank}}</p>` |
+| `sel_r1-_ggplusggg` | blank before trailing tokens | `populate_blank` | `text` | `<p>{{blank}} {after_1}{after_2}</p>` |
+| `sel_r1-s3_plusggg` | stimulus-heavy/image-first variant | `populate_blank` | `text` or `image` | include stimulus in `prompt`/`sentenceHtml`; keep single blank in `template` |
+
+Notes:
+
+- `choiceMode` should be `image` only when distractors are image choices; otherwise use `text`.
+- Current model contract is single-blank for `populate_blank`; dual-cloze source shapes are normalized to one `{{blank}}`.
+- `correctChoiceId` should always map from Learnosity `valid_response.name` (`distractor_n` -> `cN`).
+- Layout defaults are tuned from original CQT visual baselines, but they are not fixed: override through `model.layoutLimits` when host/theme requirements differ.
 
 ## Authoring model
 
 - **`prompt`** (optional) and **`promptEnabled`**
 - **`template`**: HTML string containing exactly one literal `{{blank}}` token
+- **`interactionMode`**: `populate_blank` | `audio_mc_only`
 - **`choiceMode`**: `text` | `image`
 - **`choices`**: `{ id, labelHtml? }` or `{ id, imageUrl, imageAlt }` per mode
 - **`correctChoiceId`**
-- **`hasAudio`**, **`audioUrl`**, **`audioTranscript`** (optional)
+- **`hasAudio`**, **`audioUrl`**, **`audioTranscript`** (`audioUrl` required when `hasAudio=true`)
+- **`autoplayAudioEnabled`**, **`completeAudioEnabled`** (optional integration flags)
+- **`layoutLimits`** (optional): numeric visual constraints; defaults are based on current CQT parity behavior and can be overridden per item
+- **`layoutProfilePresets`** (optional): named preset map by `layoutProfile`; use profile as a template and override with `layoutLimits`
+- **`audioButtonSkin`** / **`audioButtonSkinsByLocale`** (optional): override listen-button skin URLs
+- **`uiText`** (optional): override labels/messages (show/hide correct, answer choices, autoplay prompt, transcript label, missing-audio message)
+
+### `layoutLimits` keys (all optional, positive numbers)
+
+- `blankStandaloneWidthRem`
+- `blankWideWidthRem`
+- `blankUnderlineWidthPx`
+- `blankUnderlineWideWidthPx`
+- `horizontalChoiceWidthPx`
+- `horizontalChoiceWidthVw`
+- `horizontalChoiceTileMinHeightRem`
+- `horizontalChoiceContentMinHeightRem`
+- `selectedImageMaxHeightRem`
+- `choiceImageMaxHeightRem`
+- `listenButtonSizePx`
+- `stimulusMinColumnPx`
+- `textMinColumnPx`
+- `legendMaxChars`
+- `choiceGroupGapRem`
+- `choiceRowGapRem`
+- `toggleButtonGapRem`
+- `horizontalChoiceRadioTopMarginRem`
+- `audioBlankTemplateMarginTopRem`
+- `audioBlankTemplateMarginBottomRem`
+- `stimulusGridColumnGapRem`
+- `stimulusGridRowGapRem`
+- `stimulusSentenceMarginTopRem`
+- `stimulusChoicesMarginTopRem`
+- `tokenGridColumnGapRem`
+- `tokenGridRowGapRem`
+- `tokenTemplateMarginTopRem`
+- `tokenInlineTokenGapRem`
+- `tokenChoicesMarginTopRem`
+- `inlineGridColumnGapRem`
+- `inlineGridRowGapRem`
+- `inlineTemplateMarginTopRem`
+- `inlineChoicesMarginTopRem`
 
 ## Session
 
 - **`choiceId`**: selected choice id
 
+## Implementation hints
+
+- **Controller invariants:** in `populate_blank`, template must contain exactly one `{{blank}}`; in `audio_mc_only`, template must not contain `{{blank}}`.
+- **Choice normalization:** choices are polymorphic by `choiceMode` (text via `labelHtml`, image via `imageUrl`/`imageAlt`).
+- **Delivery rendering:** template is split around `{{blank}}`; selected choice content is rendered into the blank slot.
+- **Layout limits are model-driven:** delivery reads `model.layoutLimits` (blank widths/underline widths, choice tile sizing, image max heights, listen button size, layout column minimums); defaults are CQT-informed but overrideable.
+- **Evaluate mode behavior:** when evaluate/correct-answer mode is enabled, delivery can render `correctChoiceId` in the blank/choice state.
+- **Audio error behavior:** no TTS fallback is used; when `hasAudio=true` and no playable `audioUrl` is provided, delivery shows an explicit error message (configurable via `uiText.audioResourceUnavailable`).
+- **Print parity:** print view mirrors prompt/template/choice presentation with the same blank-token contract.
+
+## Theming hooks (`pie-*` classes)
+
+Delivery now exposes stable `pie-*` classes so hosts can theme this element with the same class-oriented approach used by other PIE elements.
+
+- Root/container: `pie-element`, `pie-element-mc-populated-blank`, `pie-delivery-root`
+- Prompt/audio/template: `pie-prompt`, `pie-audio-container`, `pie-audio-player`, `pie-audio-transcript`, `pie-template-line`, `pie-sentence-line`
+- Blank display: `pie-blank-slot`, `pie-blank-slot-standalone`, `pie-blank-value`, `pie-blank-image`
+- Choice group: `pie-choices-fieldset`, `pie-choices-legend`, `pie-choices`
+- Choice rows/items: `pie-choice`, `pie-choice-horizontal`, `pie-choice-selected`, `pie-choice-label`, `pie-choice-image`
+- Choice controls: `pie-choice-radio`, `pie-choice-radio-inline`, `pie-choice-radio-bottom`
+- Evaluate/toggle feedback: `pie-toggle-correct-answer`, `pie-result-feedback`, `pie-choice-feedback-correct`, `pie-choice-feedback-incorrect`
+
 ## Builds
 
 Same layout as `@pie-element/simple-cloze`: `delivery`, `controller`, `author`, `print`, plus IIFE bundle for script-tag loading.

packages/elements-svelte/mc-populated-blank/README.md

@@ -30,9 +30,6 @@
       "development": "./src/print/index.ts",
       "types": "./dist/print/index.d.ts",
       "default": "./dist/print/index.js"
-    },
-    "./iife": {
-      "default": "./dist/index.iife.js"
     }
   },
   "files": [

packages/elements-svelte/mc-populated-blank/package.json

@@ -1,5 +1,41 @@
 /** Token authors must include exactly once in `template` (HTML). */
 export const BLANK_TOKEN = '{{blank}}';
+/** Baseline values tuned to match historical CQT visuals; override via model.layoutLimits. */
+export const DEFAULT_LAYOUT_LIMITS = {
+  blankStandaloneWidthRem: 7,
+  blankWideWidthRem: 10,
+  blankUnderlineWidthPx: 2,
+  blankUnderlineWideWidthPx: 4,
+  horizontalChoiceWidthPx: 170,
+  horizontalChoiceWidthVw: 30,
+  horizontalChoiceTileMinHeightRem: 11,
+  horizontalChoiceContentMinHeightRem: 7.5,
+  selectedImageMaxHeightRem: 4,
+  choiceImageMaxHeightRem: 5,
+  listenButtonSizePx: 128,
+  stimulusMinColumnPx: 210,
+  textMinColumnPx: 260,
+  legendMaxChars: 120,
+  choiceGroupGapRem: 0.5,
+  choiceRowGapRem: 0.5,
+  toggleButtonGapRem: 0.5,
+  horizontalChoiceRadioTopMarginRem: 0.5,
+  audioBlankTemplateMarginTopRem: 0.8,
+  audioBlankTemplateMarginBottomRem: 1.8,
+  stimulusGridColumnGapRem: 2,
+  stimulusGridRowGapRem: 0.7,
+  stimulusSentenceMarginTopRem: 0.2,
+  stimulusChoicesMarginTopRem: 0.9,
+  tokenGridColumnGapRem: 1.5,
+  tokenGridRowGapRem: 0.8,
+  tokenTemplateMarginTopRem: 0.6,
+  tokenInlineTokenGapRem: 0.35,
+  tokenChoicesMarginTopRem: 0.2,
+  inlineGridColumnGapRem: 1.5,
+  inlineGridRowGapRem: 0.65,
+  inlineTemplateMarginTopRem: 0.45,
+  inlineChoicesMarginTopRem: 0.25,
+} as const;
 
 export default {
   model: {
@@ -10,6 +46,21 @@ export default {
     interactionMode: 'populate_blank' as const,
     layoutProfile: '',
     choiceLayout: '',
+    layoutProfilePresets: {},
+    layoutLimits: { ...DEFAULT_LAYOUT_LIMITS },
+    audioButtonSkin: null,
+    audioButtonSkinsByLocale: {},
+    uiText: {
+      answerChoices: 'Answer choices',
+      selectedAnswerInSentence: 'Selected answer in sentence',
+      showCorrectAnswer: 'Show correct answer',
+      hideCorrectAnswer: 'Hide correct answer',
+      clickToEnableAutoplay: 'Click to enable audio autoplay',
+      audioResourceUnavailable: 'Audio is enabled but no playable audio URL is configured.',
+      transcriptLabel: 'Transcript',
+      listenLabelEn: 'Listen',
+      listenLabelEs: 'Escuchar',
+    },
     sentenceHtml: '',
     template: `<p>The answer is ${BLANK_TOKEN}.</p>`,
     choiceMode: 'text' as const,