Book Creation Wizard

[Eliezir]

Book Creation Wizard

Replaces the old multi-step book creation form with a new full-screen wizard. The wizard guides the user through preset selection and four configuration steps, generating the full AppConfig for the new book.

---

Wizard Steps

Step 0 — Preset Selection

Full-screen card picker. The user selects a preset (Textbook, Storybook, Reference, or Custom), which pre-fills the form defaults and recommendations for all subsequent steps.

Step 1 — Basic Information

PDF upload, project label, and optional page range (start/end page). The label is validated against existing book labels to prevent duplicates.

Step 2 — Visual Layout

Render strategy selection (Dynamic AI, Dynamic Overlay, Single Column, Two Columns, Two Columns Story), page grouping (single pages vs. spreads), and page sectioning mode (page-level, dynamic, or section-level). A live preview pane renders a mock of the selected strategy.

Step 3 — Content Processing

Activity generator toggle, image filters (min/max side), image cropping, and image segmentation. The preview pane shows a contextual mock for each setting group (image filter, cropping, segmentation).

Step 4 — Languages

Editing language (the language shown in the ADT while the editor is working on the book — may differ from the book's original language) and output languages (the languages published for readers). The preview shows a two-panel mock with a live summary sentence.

Step 5 — Style Guide (implemented, temporarily disabled)

We built a full Style Guide step that lets the user pick a style guide (typography, colors, and component layout for generated pages) with an iframe preview of the selection. The step is commented out in the wizard for now (STEPS in steps.ts, with Step5 still in the codebase) until we settle the best product use cases for it. We can re-enable it, move it elsewhere, or drop it once that is clear.

---

How Presets Work

Presets are defined in apps/studio/src/components/wizard/constants.ts as entries in the PRESETS array. Each preset has:

• id — unique identifier (textbook, storybook, reference, custom)
• title / description — displayed in the preset card
• recommendedFor — bullet list shown in examplesModal
• exampleBooks — books shown as examples for that preset (see below)
• renderStrategies — the subset of render strategies available for this preset
• recommendedStrategies — strategies that get a "Recommended" badge in the picker
• recommendations — a Partial<WizardFormValues> that controls which options show a recommendation indicator across all subsequent steps (render strategy, page grouping, sectioning mode, activities, etc.)
• formDefaults — values pre-filled into the form when the preset is selected (e.g. image filter bounds)
• baseConfig — the full pipeline config block that gets spread into the book's AppConfig at creation time. This is where LLM model names, prompt names, timeouts, temperatures, and render strategy configs live.

There are no YAML preset files. All preset config — including machine-level pipeline config — lives in constants.ts. The buildConfigOverrides() function in bookCreationConfig.ts merges baseConfig with the wizard form values to produce the final config.yaml written to the new book directory.

Adding a New Preset

1. Add a new entry to PRESETS in constants.ts with all required fields.
2. Add the new id to the PresetId union type in the same file.
3. Add the new id to LayoutType in packages/types/src/config.ts if it maps to a new layout type.
4. Optionally add a getPresetAccent() entry for the color scheme.
5. If the preset needs a visual preview in the card, create a wireframe preview component and set it as Icon.

---

How to Add a New Wizard Step

1. Create a new directory apps/studio/src/components/wizard/stepNYourStep/ with an index.tsx that exports the step component.
2. Create a YourStepPreviewPane.tsx in the same directory. Use the shared PreviewShell component from shared/PreviewShell.tsx as the outer wrapper.
3. Add a new entry to the STEPS array in steps.ts with title, description, component, and isValid.
4. Wire up the preview pane in BookCreationWizard.tsx inside renderPreviewContent() — match on currentStep index.
5. Add any new form fields to WizardFormValues in wizardForm.ts and initialize them in defaultValues.
6. Update buildConfigOverrides() in bookCreationConfig.ts to map the new form fields to AppConfig keys.

---

Example Books — Still Needs Work

Each preset has an exampleBooks array. Currently all presets share the same placeholder PDF/ADT URLs (DEMO_PDF_URL / DEMO_ADT_URL). We still need to define real books and ADT instances to show as examples for each preset. Books marked comingSoon: true show a badge instead of a link. Once real assets are available, replace the shared demo URLs with per-preset ones in each preset's exampleBooks entries.

---

Open Questions

Should we keep the preset color scheme throughout the wizard?

Right now, once the user selects a preset, its accent color propagates through the entire wizard — step counter, navigation buttons, recommendation badges, and the "Step N of N" label all adopt the preset's hue. This creates a sense of continuity but adds visual complexity. Should we keep this, simplify to a single brand color, or limit the accent to just the preset step?

Activity generator off — what should happen to activity sections?

When generate_activities is disabled, the current behavior is to prune all activity section types entirely — they are removed from the book as if they don't exist. Is this the right behavior, or should disabled activities be kept as static PDF page screenshots instead? The pruning approach is simpler and avoids partial content, but it may surprise users who expect to see the original page even when activities are off.

[elasticsounds]

@Eliezir are you waiting for approval of the UI before adding the dependencies to packages.json?

[elasticsounds]

For the missing demonstration books @gbergengruen will collect the following to share with you.

Textbooks

• Brazil (PDF)
• Brazil - generated textbook
• Cuaderno5 Chapter 1 (PDF)
• Cuaderno5 Chatper 1 - hosted HTML (with activities)
• Egypt (PDF)
• Egypt - hosted HTML + Quiz

Storybook

• Momo (PDF)
• Momo Multilingual (with quiz)
• Queremos (PDF)
• Queremos - hosted HTML
• Triste (PDF)
• Triste Demo

Reference

• Biologicas (PDF)
• Biologicas - HTML output
• Any public report with science or data tilt from UNICEF?

[Eliezir]

Incredible! I really love the UI, it feels polished and easy/intuitive. Couple of notes.

• Not obvious that section mode is below the fold on choose layout screen.
• Headings for each section are not consistent across the steps (mixing capitals, sentence case) choose one layout.
• Missing new toggle (complex figure extraction) "Detects complex charts, and figures that contain a mix of text, vectors and images and crops them out of the page"

Just finished the changes, sorry for the delay.

• Section mode below the fold — kept the button always enabled, but when the user clicks Next while something is missing it scrolls and focuses the blocking input and shows a small hint above the button pointing to what needs to be filled. Let me know what you think of that approach.
• Heading consistency — went with sentence case across all steps, removing the uppercase/tracking-wide style that was only on Step 3.
• Figure extraction toggle — added it. I went with figureExtraction as the field name, mapping to vector_text_grouping in the config. Marked it as recommended for Textbook and Reference
• presets since those are the ones most likely to have complex charts and mixed figures. Storybook stays off by default.
• Added the auto increment label [Wizard] Auto-increment label if re-adding the same PDF #223

Two questions while I have you:

1. When the user turns off Activities Generator, we're currently pruning those sections — is that still the right behaviour, or should we keep them and just not convert them to interactive
   elements?
2. Confirming figureExtraction → vector_text_grouping is the correct mapping

[Eliezir]

@Eliezir are you waiting for approval of the UI before adding the dependencies to packages.json?

Not really, Its already on the branch apps/studio/package.json

[elasticsounds]

Ok when I thought there was a package I had to install but I may be mistaken - not a big deal Sent from Gmail Mobile

…

On Mon, Apr 6, 2026 at 5:30 PM Eliezir Moreira ***@***.***> wrote: *Eliezir* left a comment (unicef/adt-studio#235) <#235 (comment)> @Eliezir <https://github.com/Eliezir> are you waiting for approval of the UI before adding the dependencies to packages.json? Not really, Its already on the branch apps/studio/package.json <https://github.com/unicef/adt-studio/pull/235/changes#diff-14a87cb8301b0736bd6722d3ad7b33f96f0da057b76a9aa6d98537b2a5ff69ce> — Reply to this email directly, view it on GitHub <#235 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABNBVFYPN2QHHDDCDAYFSAD4UQOZHAVCNFSM6AAAAACXLMI7QWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCOJVGEYTSMBSHE> . You are receiving this because your review was requested.Message ID: ***@***.***>

[gbergengruen]

For the missing demonstration books @gbergengruen will collect the following to share with you.

Textbooks

• Brazil (PDF)
• Brazil - generated textbook
• Cuaderno5 Chapter 1 (PDF)
• Cuaderno5 Chatper 1 - hosted HTML (with activities)
• Egypt (PDF)
• Egypt - hosted HTML + Quiz

Storybook

• Momo (PDF)
• Momo Multilingual (with quiz)
• Queremos (PDF)
• Queremos - hosted HTML
• Triste (PDF)
• Triste Demo

Reference

• Biologicas (PDF)
• Biologicas - HTML output
• Any public report with science or data tilt from UNICEF?

Hey guys, I have just sent an email to both of you with most of the resources requested here... I'm missing out some...

[elasticsounds]

Re: Activities Generator off behavior

Good question. If I have turned off activity generation, it should route those section types to the default render strategy, not the activity types.

Re: figureExtraction → vector_text_grouping mapping

Yes, that’s the correct mapping. vector_text_grouping is the backend config key. Good call making it recommended for Textbook and Reference but off for Storybook.

[elasticsounds]

I did a code review pass — a few things to address before merge:

Bugs to fix:

• handleCreate() has an empty catch {} on api.runStages (line 268) — at minimum log the error so we can debug pipeline failures. A toast/warning would be even better.
• Double-click race on the Create button — isCreating state update is async so a fast double-click can fire handleCreate twice. Simplest fix: use createMutation.isPending instead of the manual isCreating state (which also fixes the issue where isCreating never resets on success).
• When imageSegmentation is enabled but segmentationMinSide is empty, buildConfigOverrides produces { min_side: NaN }. Either require a value when segmentation is on, or skip the field when empty.
• Duplicate name validation has a race: if useBooks() is still loading, existingBookLabels is [] and a duplicate name passes validation.
• No page range validation — buildConfigOverrides parses startPage and endPage to numbers but there’s no check that startPage <= endPage or that either is positive. Invalid values like startPage: 50, endPage: 3 would be sent straight to the API.
• Small UX items:

The “Required Fields” badge shows on Step 4 (Languages) even though nothing is required there.
Everything else looks great — the validation hints + scroll-to-invalid behavior is a really nice touch.

[Eliezir]

I did a code review pass — a few things to address before merge:

Bugs to fix:

• handleCreate() has an empty catch {} on api.runStages (line 268) — at minimum log the error so we can debug pipeline failures. A toast/warning would be even better.
• Double-click race on the Create button — isCreating state update is async so a fast double-click can fire handleCreate twice. Simplest fix: use createMutation.isPending instead of the manual isCreating state (which also fixes the issue where isCreating never resets on success).
• When imageSegmentation is enabled but segmentationMinSide is empty, buildConfigOverrides produces { min_side: NaN }. Either require a value when segmentation is on, or skip the field when empty.
• Duplicate name validation has a race: if useBooks() is still loading, existingBookLabels is [] and a duplicate name passes validation.
• No page range validation — buildConfigOverrides parses startPage and endPage to numbers but there’s no check that startPage <= endPage or that either is positive. Invalid values like startPage: 50, endPage: 3 would be sent straight to the API.
• Small UX items:

The “Required Fields” badge shows on Step 4 (Languages) even though nothing is required there. Everything else looks great — the validation hints + scroll-to-invalid behavior is a really nice touch.

Hey @elasticsounds, I fixed all the reported bugs, the double-click race, the api.runStages logging, the segmentationMinSide NaN case, the page range validation, and the Require Fields badge on Step 4.

For the double-click: didn't go with createMutation.isPending because it only covers the mutation itself, once the book is created the flag drops to false, but api.runStages and navigate haven't run yet, causing a visible flicker back to the normal button before navigation. Used a local isCreating state (spans the full flow) with a synchronous useRef guard to block re-entry before React re-renders.

Extra changes made:

• Activity generator off behavior: reverted the section type pruning, activity sections are still generated by the LLM but routed to the default render strategy instead of the activity renderer.
• PDF validation: corrupted or password-protected PDFs are now auto-removed on upload, with a persistent error hint shown until the user selects a new valid file.