@pitcher/js-api 1.29.0 → 1.31.0

package/lib/apps/canvas-builder/types/canvas.d.ts

@@ -172,12 +172,33 @@ export interface CanvasFile {
 declare const MULTIMEDIA_IMG_TYPE: {
     readonly external: "external";
     readonly pitcher_asset: "pitcher_asset";
+    readonly ld_asset: "ld_asset";
 };
 export declare enum MultimediaHorizontalAlignmentOptions {
     LEFT = "left",
     CENTER = "center",
     RIGHT = "right"
 }
+/**
+ * Where a Multimedia `poster_url` came from — shared by every asset variant, because a poster's origin is
+ * independent of the media's (an `external` video can carry an L&D-hosted poster).
+ *
+ * `poster_url` alone is unrefreshable: a short-lived source (an L&D presigned URL, 900s) rots and the
+ * canvas has no record of what it was, so nothing can re-resolve it — unlike `file.content_url`, which
+ * `Multimedia.vue` refreshes at render off `file.id`. Recording the id plus its backend is what keeps a
+ * poster recoverable.
+ *
+ * Both are absent for an external-link/Pexels poster (long-lived URL, no Pitcher id to resolve).
+ *
+ * `poster_asset_type` lives on the NODE rather than being read from host state at render, because the
+ * render path must work in COURSE (rep playback) — the mode where a poster is *guaranteed* to be past its
+ * TTL — and COURSE cannot supply `CanvasBuilderProps.assetType` at all (it's `?: never` there).
+ * (T1.7b / PIT-7742, R4-F1.)
+ */
+type MultimediaPosterProvenance = {
+    poster_file_id?: string;
+    poster_asset_type?: 'pitcher_asset' | 'ld_asset';
+};
 export type ExternalMultimediaAssetType = {
     asset_type: typeof MULTIMEDIA_IMG_TYPE.external;
     external_url: string;
@@ -186,7 +207,7 @@ export type ExternalMultimediaAssetType = {
     from?: 'custom' | 'pexels' | 'unsplash' | 'ai';
     poster_url?: string;
     poster_background_size?: BackgroundSize;
-};
+} & MultimediaPosterProvenance;
 export type PitcherMultimediaAssetType = {
     asset_type: typeof MULTIMEDIA_IMG_TYPE.pitcher_asset;
     file: {
@@ -198,8 +219,20 @@ export type PitcherMultimediaAssetType = {
     horizontal_alignment?: MultimediaHorizontalAlignmentOptions;
     poster_url?: string;
     poster_background_size?: BackgroundSize;
-};
-export type MultimediaProps = ExternalMultimediaAssetType | PitcherMultimediaAssetType;
+} & MultimediaPosterProvenance;
+export interface LdMultimediaAssetType extends MultimediaPosterProvenance {
+    asset_type: typeof MULTIMEDIA_IMG_TYPE.ld_asset;
+    file: {
+        id: File['id'];
+        name: File['name'];
+        content_url?: File['content_url'];
+    };
+    type: 'image' | 'video';
+    horizontal_alignment?: MultimediaHorizontalAlignmentOptions;
+    poster_url?: string;
+    poster_background_size?: BackgroundSize;
+}
+export type MultimediaProps = ExternalMultimediaAssetType | PitcherMultimediaAssetType | LdMultimediaAssetType;
 export type ContentGridCommonFileProps = {
     id: FileRetrieve['id'];
     snapshot_id?: FileRetrieve['id'];
@@ -599,6 +632,7 @@ export type SharingBuilderProps = NoCRMBuilderProps & {
     };
     activeCanvas: CanvasRetrieve;
     onExit: () => void;
+    onEndCall?: () => void | Promise<void>;
     onSave?: never;
     onEnter?: () => void;
     onPageEnter?: (data: ComponentNode[], pageIndex: number) => void;
@@ -626,6 +660,7 @@ export type SharingBuilderProps = NoCRMBuilderProps & {
     listRecommendedFiles?: never;
     listCanvases?: never;
     fetchFolder?: never;
+    assetType?: never;
     fetchFile: (fileId: FileRetrieve['id']) => Promise<FileRetrieve>;
     fetchInstanceMetadataTemplate?: never;
     fetchCanvas?: (canvasId: CanvasRetrieve['id'], params?: Record<string, any>) => Promise<CanvasRetrieve>;
@@ -677,6 +712,7 @@ type AdminImpactCommonBuilderProps = {
     };
     activeCanvas: CanvasRetrieve;
     onExit: () => void;
+    onEndCall?: () => void | Promise<void>;
     onEnter?: () => void;
     onComponentEnter?: (data: ComponentNode | CanvasRetrieve, params: ComponentTrackingParams) => void;
     onComponentExit?: (data: ComponentNode | CanvasRetrieve, params: ComponentTrackingParams) => void;
@@ -735,6 +771,31 @@ type AdminImpactCommonBuilderProps = {
     isAnyTypeOfAdmin: boolean;
     canvasMetadata: CanvasMetadataRetrieve | null;
     hideEdit?: boolean;
+    /**
+     * PIT-8361 QA — the host cannot yet tell whether this canvas is frozen, so its `hideEdit` is a
+     * fail-safe placeholder rather than an answer.
+     *
+     * Only `isWizardOwnedEditSurface` reads it, and only to avoid concluding "not a wizard surface"
+     * from a `hideEdit` that means "don't know yet" — which dropped the rep into the RAW canvas
+     * editor on a wizard-driven canvas for the length of one API call. The WRITE guard
+     * (`shouldAutoOpenCompletionWizard`) deliberately still refuses while `hideEdit` is true.
+     *
+     * Falsy default is the safe one — a host that never sets it behaves exactly as before, which
+     * also keeps it clear of Vue's absent-boolean-is-`false` casting.
+     */
+    isFreezePending?: boolean;
+    /**
+     * Which asset backend the Assets tab's files come from, stamped onto a Multimedia node on selection
+     * (`prepareMultimediaNodeData`). Defaults to `'pitcher_asset'`, so every existing sales/DSR/admin
+     * mount is unchanged — only the L&D course host (course-canvas-host) opts into `'ld_asset'`.
+     *
+     * Lives on the Admin/Impact/Home common props because those are the only modes that can open the
+     * content selector; SHARING/COURSE type-block it with `?: never`.
+     *
+     * It does NOT affect rendering — Multimedia keys its render-time URL re-resolution off the node's
+     * own `asset_type`, so an `ld_asset` node renders correctly wherever it is mounted. (T1.7b/PIT-7742)
+     */
+    assetType?: 'pitcher_asset' | 'ld_asset';
 };
 type AdminBuilderProps = AdminImpactCommonBuilderProps & (CRMBuilderProps | NoCRMBuilderProps) & {
     isRedirectEvent?: never;
@@ -784,6 +845,7 @@ export type CourseBuilderProps = NoCRMBuilderProps & {
     };
     activeCanvas: CanvasRetrieve;
     onExit: () => void;
+    onEndCall?: () => void | Promise<void>;
     onSave?: (canvasId: CanvasRetrieve['id'], canvas: PatchedCanvasUpdateRequest & {
         fields?: string;
         include_expired_files?: boolean;
@@ -814,6 +876,7 @@ export type CourseBuilderProps = NoCRMBuilderProps & {
     listRecommendedFiles?: never;
     listCanvases?: never;
     fetchFolder?: never;
+    assetType?: never;
     fetchFile: (fileId: FileRetrieve['id']) => Promise<FileRetrieve>;
     fetchInstanceMetadataTemplate?: never;
     fetchCanvas?: (canvasId: CanvasRetrieve['id'], params?: Record<string, any>) => Promise<CanvasRetrieve>;

package/lib/apps/canvas-builder/util/canvas.util.d.ts

@@ -57,6 +57,18 @@ type FoundComponent = {
 } | null;
 export declare function findEmbeddableInSectionsContent(canvasPages: ComponentNode[][], sectionComponentNodesBySectionId: UnwrapRef<SectionComponentNodesBySectionId>, appName: string): FoundComponent;
 export declare function findAllEmbeddableTypesInCanvasContent(componentNodesById: UnwrapRef<ComponentNodesById>): Set<string>;
+/**
+ * Section ids the deck's OWN content references (SectionList/ContentList `data.sections`).
+ *
+ * `activeCanvas.sections` is a strict SUPERSET of these: Django's `prefetch_sections`
+ * deliberately merges the TEMPLATE's sections in (so wizard steps and pickers can offer
+ * them), and the presentation-tools modal registers lookup-only entries (PIT-8031).
+ * Anything that means "what is actually presentable in this deck" — the embeddable
+ * shortcut icons chiefly — must filter the lookup through these ids, or it renders
+ * affordances for slides that do not exist (PIT-8031 QA Q1: dead tool shortcuts on any
+ * deck whose template carries tool groups the rep never selected).
+ */
+export declare function findReferencedSectionIdsInCanvasContent(componentNodesById: UnwrapRef<ComponentNodesById>): Set<string>;
 export declare function findAllEmbeddableTypesInSectionsContent(sectionComponentNodesBySectionId: UnwrapRef<SectionComponentNodesBySectionId>): Set<string>;
 export declare function findEmbeddableInCanvasContent(componentNodesById: UnwrapRef<ComponentNodesById>, appName: string): FoundComponent;
 export declare function scrollToComponentById(id: ComponentNode['id'] | null | undefined, sectionId?: string, sectionIndex?: number, instant?: boolean, delay?: number): void;

package/lib/apps/canvas-builder/util/completionWizard.util.d.ts

@@ -0,0 +1,347 @@
+import { CanvasActions } from '../../../types/canvasActions';
+import { ComponentNode } from '../types/canvas';
+import { AppFile } from '../../../types/app';
+/** Installable-app name of the React pitchdeck wizard (PIT-7510). */
+export declare const REACT_COMPLETION_WIZARD_APP_NAME = "pitchdeck-wizard-ng";
+export interface ResolveCompletionWizardVariantParams {
+    /** `canvas.enable_react_completion_wizard` org/instance setting — opt-in, default off. */
+    isReactWizardSettingEnabled: boolean;
+    /** The React wizard app resolved to a loadable URL (installed or local dev override). */
+    isReactWizardAvailable: boolean;
+    /**
+     * The host has not delivered the installed-apps roster yet (PIT-7992): `undefined` apps,
+     * as opposed to a loaded-but-empty list. While pending, "no React app" cannot be told
+     * apart from "not loaded yet", so the decision is deferred rather than falling back.
+     */
+    isRosterPending?: boolean;
+}
+/**
+ * PIT-7510: which completion-wizard implementation to render where the wizard opens today.
+ * The setting is the only switch (no LaunchDarkly flag); an enabled setting without an
+ * installed app falls back to the Vue wizard so no flow is ever lost.
+ *
+ * An enabled instance NEVER sees the Vue wizard for config reasons (PIT-8021 QA Q3,
+ * decided by Bastien in comment 515871): templates carrying group features the React
+ * wizard does not implement — visibility rules, repetition rules — still open the React
+ * wizard, which simply does not apply them (the groups behave as ordinary groups). The
+ * earlier per-deck fallback honored those rules but meant an admin ticking one condition
+ * silently swapped every rep back to the legacy flow, which reads as a regression.
+ *
+ * `'pending'` (PIT-7992): the React setting is on but the host's app roster hasn't loaded,
+ * so availability is unknowable. Deciding 'vue' here is what flashed the LEGACY wizard on
+ * templates with a non-app step ('wizard' strategy passes `getCompletionWizardStepNodes`
+ * without the roster, so the overlay condition goes true before the roster lands) — the
+ * caller must render NEITHER wizard until the roster resolves the real variant.
+ */
+export declare function resolveCompletionWizardVariant(p: ResolveCompletionWizardVariantParams): 'vue' | 'react' | 'pending';
+/**
+ * Resolve the React wizard app's iframe URL: local dev override first (same mechanism as
+ * every installable app), else the installed app's `content_url`.
+ */
+export declare function resolveReactCompletionWizardSrc(apps: AppFile[]): string | null;
+/**
+ * PIT-7030: what cancelling the completion wizard means depends on how it was entered.
+ *
+ * Create flow (never-completed deck): cancel abandons the deck — the host emits
+ * `cancelCanvasCompletionWizard`, which slotty treats as "leave the canvas" (and deletes the
+ * deck when it came from the create-canvas modal).
+ *
+ * Edit flow (`completion_wizard.edited` — set by `retriggerWizard()`, i.e. the "Edit Wizard"
+ * button or the Edit-action auto-open): the wizard was opened over a deck that was already
+ * completed, and entering it persisted `completed: false`. Cancel must restore
+ * `completed: true` and reload into the canvas editor — exactly what the Vue wizard's
+ * `confirmCancel()` → `completeWizard()` does. Emitting the cancel event here instead exits
+ * the canvas entirely and leaves the deck stuck "In-progress" (the QA regression on the
+ * React wizard).
+ */
+interface WizardCancelCanvasContext {
+    pitcher?: {
+        /** `edited` is written only by `retriggerWizard()` — the same signal the Vue wizard's `isEditWizard` reads. */
+        completion_wizard?: {
+            edited?: boolean;
+            completed?: boolean;
+        };
+    };
+}
+export declare function shouldCompleteWizardOnCancel(canvasContext: WizardCancelCanvasContext | null | undefined): boolean;
+export interface IsWizardOwnedEditSurfaceParams {
+    /** `canvas.enable_edit_opens_completion_wizard` — the opt-in. */
+    isSettingEnabled: boolean;
+    isImpact: boolean;
+    isCanvas: boolean;
+    isCanvasPreviewMode: boolean;
+    /** The host's "this canvas is not editable" signal (frozen / RBAC / lock). */
+    hideEdit: boolean;
+    /**
+     * The host cannot yet tell whether the canvas is frozen, so `hideEdit` is a placeholder rather
+     * than an answer. See the doc comment for why this exists.
+     */
+    isFreezePending?: boolean;
+    /** The deck carries wizard steps, or wizard state from a previous session. */
+    hasWizardState: boolean;
+}
+/**
+ * PIT-7992 — whether the WIZARD owns this canvas's edit surface, i.e. a rep must never land in the
+ * raw canvas editor here because the wizard IS the deck's edit surface.
+ *
+ * PIT-8361 QA — `isFreezePending` is why this is a function rather than an inline `&&` chain.
+ * slotty computes `hideEdit` as `props.hideEdit || isCanvasFrozen`, and `isCanvasFrozen` is SEEDED
+ * TRUE for any org with the freeze flag, then corrected by an API round-trip. In that window
+ * `hideEdit: true` means "not yet known to be editable" — a fail-safe about WRITING, not a
+ * statement that this is not a wizard surface. Reading it as the latter released the surface, so
+ * nothing demoted the builder out of edit mode and the rep was dropped into the raw editor on a
+ * wizard-driven canvas for the length of one network call.
+ *
+ * Holding the surface while pending is safe either way it resolves: not frozen → the wizard opens
+ * as intended; genuinely frozen → the canvas has already been demoted out of edit mode, which is
+ * where a frozen canvas belongs. Note this only ever excuses `hideEdit` — it can never resurrect a
+ * surface the other gates rejected.
+ *
+ * The WRITE guard is deliberately NOT relaxed the same way: `shouldAutoOpenCompletionWizard` keeps
+ * its hard `hideEdit` bail, because `retriggerWizard()` persists `completed: false` and must not
+ * touch a canvas that may turn out to be frozen. It re-runs once the status resolves.
+ */
+export declare function isWizardOwnedEditSurface(p: IsWizardOwnedEditSurfaceParams): boolean;
+/**
+ * PIT-8361 — whether COMPLETING the wizard should EXIT the builder instead of reloading it.
+ *
+ * The complete path ends in `reloadAfterCompletionWizard()`, and for a DECK that is right: the
+ * wizard just rewrote the deck's `content`, the rep stays in the builder to present it, and one
+ * page load is the cheapest way to guarantee every component re-renders from the saved artifact.
+ *
+ * For a MASTER it is wrong, and visibly so. A master's builder is a place the rep is LEAVING —
+ * `savedCanvasCompletionWizard` already returns them to "My Master Pitchdecks", which refetches on
+ * arrival (`shouldRefetchOnMasterBuilderReturn`), so the freshly authored master is on screen
+ * without a reload. Reloading instead reboots the whole slotty iframe on the master builder URL,
+ * so the rep gets a flash of the master's own view state (the `enable_edit_opens_completion_wizard`
+ * demote watcher in `App.vue` rewrites edit -> present on the way back up), then the app's boot
+ * spinner, then a rebuilt sidebar — the reported defect, and never the tab they asked for.
+ *
+ * **Orthogonal to `resolveWizardFlow`**, which deliberately STOPPED special-casing masters
+ * (PIT-7488 QA Q9). That decision is about how a wizard session OPENS — create vs restore — and
+ * forcing masters to `edit` there restored them from an artifact that did not exist yet. This one
+ * is about how a session ENDS. The two read as contradictory only if you miss that distinction.
+ *
+ * Callers must also skip `markCompletionWizardAutoOpened()` on the exit branch: that marker exists
+ * purely to suppress one auto-open on the post-reload mount, so with no reload it survives and
+ * swallows the rep's next deliberate Edit (PIT-7510 Q12).
+ */
+export declare function shouldExitBuilderOnWizardComplete(p: {
+    isMaster?: boolean | null;
+}): boolean;
+/** The wizard state the flow decision reads — `context.pitcher.completion_wizard`. */
+export interface WizardFlowState {
+    /** Set by `retriggerWizard()` — the wizard was reopened over an already-completed deck. */
+    edited?: boolean;
+    completed?: boolean;
+    /** A Save & Exit draft: restores like an edit session but cancels like a draft. */
+    react_saved?: boolean;
+    /**
+     * PIT-8399 — this canvas's content was COPIED from a curated source (a master), so its own
+     * persisted artifact is the authoritative agenda even though it carries no wizard progress.
+     *
+     * Written by `buildContextFromMaster` (master -> deck) and next-core's `buildSharedCopyContext`
+     * (master -> shared copy), which both reset the source's progress so the wizard runs. It is
+     * deliberately not one of the three flags above: see `resolveWizardAgendaSource`.
+     */
+    from_master?: boolean;
+}
+export interface ResolveWizardFlowParams {
+    wizardState?: WizardFlowState | null;
+}
+/**
+ * Which flow the React wizard is opened in: `'edit'` restores from the canvas's own artifact,
+ * `'create'` seeds a fresh one.
+ *
+ * Masters are NOT special-cased here, deliberately (PIT-7488 QA Q9). They were briefly forced to
+ * `'edit'` to dodge the app's account-demanding entry dialog, and it worked — but restoring a
+ * master that had never been through the wizard meant an empty cover, an agenda rebuilt by
+ * attribution rather than seeded from the admin groups, and an "Update Pitchdeck" button, since
+ * `editorLabelKeys` reads this very value. Suppressing that dialog is now `skipEntry`'s job, which
+ * leaves this answering the only question it should: has this canvas been through the wizard
+ * before? A fresh master says no and gets `'create'`; once saved it says yes and `'edit'` restores
+ * something that actually exists.
+ */
+export declare function resolveWizardFlow(p: ResolveWizardFlowParams): 'create' | 'edit';
+/**
+ * PIT-8399 — where the CREATE flow's agenda comes from: the admin group config, or this deck's own
+ * persisted artifact.
+ *
+ * A second declared fact rather than a lookup on `resolveWizardFlow`, for the reason `target_kind`
+ * is one (PIT-8361): the flow says whether the deck has been through the wizard, this says whether
+ * its content was authored somewhere else first. Both are true of a deck built from a master —
+ * never wizarded ITSELF, but carrying a complete artifact copied from the master — and that pair is
+ * exactly what one boolean could not express. Overloading `completion_wizard`'s presence to answer
+ * both is the reported defect: stripping it made the deck look never-curated, so the wizard reseeded
+ * its agenda from the admin groups and every custom agenda point the master carried vanished.
+ *
+ * `'artifact'` therefore requires `from_master` AND no progress of the deck's own. Progress means
+ * `resolveWizardFlow` already answers `'edit'`, whose full restore supersedes this — the deck has
+ * been saved since it was copied, so its artifact is its own rather than the master's. Stating the
+ * precedence here keeps the app's gate a plain equality check instead of a second copy of this rule.
+ */
+export declare function resolveWizardAgendaSource(p: ResolveWizardFlowParams): 'config' | 'artifact';
+/**
+ * The `completed: true` write that undoes `retriggerWizard()`'s `completed: false`.
+ *
+ * Both wizard hosts persist it on the edit-cancel and the torn-down-mid-session paths, and both
+ * must write context AND metadata (the deck's In-progress/Completed badge reads `metadata`, the
+ * wizard's own guards read `context` — leaving one behind desyncs the badge from the flow).
+ */
+export declare function buildCompletedStateRestore(canvasContext: Record<string, any> | null | undefined, canvasMetadata: Record<string, any> | null | undefined): {
+    context: Record<string, any>;
+    metadata: Record<string, any>;
+};
+/**
+ * The SectionList/ContentList nodes that become completion-wizard steps — the single source of
+ * truth behind `useCanvasCompletionWizard`'s `sectionListNodes` (and so `isCompletionWizardEnabled`).
+ *
+ * Extracted as a pure function because hosts need the same answer BEFORE the canvas-builder mounts:
+ * slotty decides whether to auto-enter fullscreen while it still only has the raw canvas record
+ * (PIT-7720 Q1). Duplicating the predicate there would silently drift from the wizard's own gate.
+ *
+ * A step whose `app` strategy points at an app that is not installed (and has no local dev override)
+ * does NOT count — the wizard skips it, so a deck made only of those never opens a wizard at all.
+ */
+export declare function getCompletionWizardStepNodes(canvasContent: ComponentNode[] | null | undefined, sectionSelectorApps: AppFile[]): ComponentNode[];
+export interface HasPendingCompletionWizardParams {
+    /** The deck's component tree (`canvas.content`). */
+    canvasContent: ComponentNode[] | null | undefined;
+    /** Installed section-selector apps — the same list the builder provides as `sectionSelectorApps`. */
+    sectionSelectorApps: AppFile[];
+    /** The deck's `canvas.context`; `pitcher.completion_wizard.completed` decides "still pending". */
+    canvasContext: {
+        pitcher?: {
+            completion_wizard?: {
+                completed?: boolean;
+            };
+        };
+    } | null | undefined;
+}
+/**
+ * Whether opening this deck lands the rep in the completion wizard — the host-side mirror of
+ * `isCompletionWizardShowing` (`wizard has steps && !completed`), answerable from the raw canvas
+ * record alone.
+ *
+ * PIT-7720 Q1: used to suppress the PIT-7029 auto-fullscreen, which otherwise wraps the WIZARD in
+ * native browser fullscreen on open — the rep is still building the deck, not presenting it.
+ */
+export declare function hasPendingCompletionWizard(p: HasPendingCompletionWizardParams): boolean;
+export declare function isCompletionWizardReloadInProgress(): boolean;
+/**
+ * Drop the slide-anchor query params (`section` + `component`, written by the present
+ * view's `router.replace`) from a URL, wherever the host's router keeps its query:
+ * slotty is hash-history (the params sit INSIDE `#/...?...`), other hosts are plain
+ * history (real `?...`). Both places are cleaned; everything else is preserved.
+ */
+export declare function stripWizardSlideAnchor(href: string): string;
+/**
+ * One-shot reload-survival marker paired with the URL strip below, consumed by the HOST's
+ * builder boot (slotty `CanvasBuilder.vue`): ignore any slide anchor on the route for the
+ * one boot that follows a post-wizard reload. The strip alone is not enough — slotty runs
+ * inside the Impact shell, and the shell's location ROOT survives the iframe reload and
+ * RESTORES the pre-wizard route (query included) into slotty's router before the builder
+ * mounts, resurrecting the anchor the strip just removed (PIT-8021 QA Q5 round 2: the
+ * regenerated deck opened mid-deck again with the strip deployed). sessionStorage so it
+ * survives exactly the reload and nothing else; consumed on first read so a later manual
+ * navigation with a real anchor works normally.
+ */
+export declare function consumeWizardReloadAnchorSkip(): boolean;
+/** `reload` is injectable only because jsdom's `window.location` is unforgeable in tests. */
+export declare function reloadAfterCompletionWizard(reload?: () => void): void;
+export declare function wasCompletionWizardAutoOpened(canvasId: string): boolean;
+export declare function markCompletionWizardAutoOpened(canvasId: string | undefined): void;
+/**
+ * Read AND clear the auto-opened marker (PIT-7510 QA Q12). The marker exists to survive the
+ * `window.location.reload()` that follows completing/cancelling the wizard — one page load.
+ * Left in place it suppressed every LATER Edit action for the rest of the browser session,
+ * so the wizard never auto-opened again. Consuming it on read keeps the reload covered
+ * (the fresh mount still sees it once) while the next explicit Edit navigation starts
+ * clean. Callers cache the consumed value per mount so re-running watcher ticks within the
+ * same mount stay suppressed.
+ */
+export declare function consumeCompletionWizardAutoOpened(canvasId: string): boolean;
+export interface ShouldAutoOpenCompletionWizardParams {
+    /** `canvas.enable_edit_opens_completion_wizard` org/instance setting — opt-in, default off. */
+    isSettingEnabled: boolean;
+    /** Impact only — the wizard is a rep-facing flow and `retriggerWizard()` bails elsewhere anyway. */
+    isImpact: boolean;
+    /** Canvases only, never templates / sections / blocks. */
+    isCanvas: boolean;
+    /** Canvas preview is read-only playback; never auto-open there. */
+    isCanvasPreviewMode: boolean;
+    /** The mode the builder was opened in (`metadata.startInMode`). */
+    startInMode?: CanvasActions;
+    /** Editing is unavailable: RBAC, `disable_canvas_edit_for_reps`, or a frozen canvas. */
+    hideEdit: boolean;
+    /** `canRetriggerWizard()` — the canvas has wizard steps AND the wizard is already completed. */
+    canRetriggerWizard: boolean;
+    /** Active canvas id — required so the caller can persist the per-canvas dedup marker. */
+    canvasId?: string;
+    /**
+     * Whether this canvas was already auto-opened in the CURRENT page load (PIT-7510 Q12). The
+     * caller reads this via `consumeCompletionWizardAutoOpened` — a read-and-clear `sessionStorage`
+     * marker (keyed by canvas id) rather than mount-local state, because the wizard completion path
+     * (`completeWizard()`) runs `window.location.reload()`, which remounts the whole builder. A
+     * mount-local flag would reset on that reload and the `{ immediate: true }` watcher would
+     * auto-reopen the wizard, producing the open→cancel→reload→reopen flash loop (PIT-7030). The
+     * marker is consumed per mount, so a LATER Edit open of the same deck auto-opens again.
+     */
+    alreadyAutoOpened: boolean;
+}
+/**
+ * PIT-7030: decide whether opening a canvas via the Edit action should reopen the completion
+ * wizard instead of landing in the canvas editor.
+ *
+ * Pure so the guard chain is unit-testable — the caller performs the (async, persisting)
+ * `retriggerWizard()` side effect.
+ *
+ * A never-completed deck already shows the wizard through `isCompletionWizardShowing`, so this
+ * only covers the completed case, which is what `canRetriggerWizard` encodes.
+ */
+export declare function shouldAutoOpenCompletionWizard(p: ShouldAutoOpenCompletionWizardParams): boolean;
+/**
+ * PIT-8361 QA Q2 — remember the mode each canvas was ENTERED in, because `startInMode` does not
+ * stay still long enough for the auto-open to read it.
+ *
+ * The defect it fixes is a race between two `{ immediate: true }` watchers in `App.vue` and slotty's
+ * URL rewrite, which is why QA saw the wizard open on some master Edits and not others:
+ *
+ * 1. The auto-open watcher runs first and bails while `completionWizardVariant` is `'pending'` —
+ *    i.e. until the HOST's installed-app roster lands (a network round-trip on a cold boot; warm
+ *    and synchronous once slotty has it, which is the "sometimes it works" half).
+ * 2. The demote watcher then fires on the same mount and sets `isEditMode = false` (correctly — the
+ *    wizard owns this surface). Slotty turns that into a new `startInMode` **through the URL**:
+ *    `edit-mode-changed` → `onEditModeChanged` → `CanvasBuilderModalView`'s local `isEditMode` →
+ *    its watcher → `debouncedUpdateUrl` (**250 ms**) → `router.replace` to the twin *present*
+ *    route → `CanvasBuilder.getStartMode()`, which on a routed open has `props.initialEditMode ===
+ *    undefined` and falls through to `isCanvasBuilderPresentRoute(route.name)` → `Present`.
+ *    (`:initialEditMode` is bound from the PROP, never from that local ref — there is no prop echo.)
+ * 3. The roster lands, the auto-open watcher re-runs — and now rejects its own canvas on
+ *    `startInMode !== Edit`. The rep is left on the raw canvas surface with no wizard, on a deck
+ *    the platform has just decided the wizard owns.
+ *
+ * So the race window is that **250 ms debounce**: a roster resolving inside it auto-opens with or
+ * without this helper, one resolving after it used to be rejected. Anyone shortening, removing or
+ * relocating `updateUrl`'s debounce is changing the wizard's behaviour. Both master child routes
+ * render the same `CanvasBuilderModalView` under an unkeyed `<RouterView>`, so step 2's `replace`
+ * patches the component in place rather than remounting it — which is what lets a latch survive
+ * the rewrite at all.
+ *
+ * Latching restores what `startInMode` is documented to mean ("the mode the builder was opened
+ * in"), which is a fact about an ENTRY and can only be observed before the host starts rewriting
+ * the URL under it. Keyed by canvas id rather than latched once per mount so that
+ * `useCanvasOverlay`, which swaps canvases in place without remounting, still gets a fresh reading
+ * per canvas — the same reason `autoOpenInFlightCanvasIds` is a set of ids.
+ *
+ * Pass-through (no latching) while the canvas id is unknown: there is nothing to key on yet, and
+ * the auto-open needs an id anyway.
+ *
+ * An UNKNOWN mode is not latched either. `startInMode` is optional on `CanvasBuilderProps`, so a
+ * host can hand over a canvas id before it has an entry mode — and latching `undefined` there would
+ * pin it forever, so the Edit that arrived a tick later could never open the wizard. That is the
+ * same defect this helper exists to fix, one layer up. Latch the first mode that is actually
+ * KNOWN, not the first observation.
+ */
+export declare function createEntryModeLatch(): (canvasId: string | undefined, startInMode: CanvasActions | undefined) => CanvasActions | undefined;
+export {};

package/lib/apps/canvas-builder/util/completionWizard.util.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/apps/canvas-builder/util/fullscreenMode.util.d.ts

@@ -0,0 +1,7 @@
+import { FullscreenMode } from '../../../types/organizationSettings.types';
+/**
+ * The presentation fullscreen mode to use: the rep's explicit in-presentation
+ * choice wins; otherwise the org/instance default; otherwise 'fullscreen'
+ * (preserving PIT-7029's auto-enter-native behaviour).
+ */
+export declare function resolvePresentationFullscreenMode(repChosen: FullscreenMode | null, defaultSetting: FullscreenMode | undefined): FullscreenMode;

package/lib/apps/canvas-builder/util/fullscreenMode.util.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/apps/canvas-builder/util/iframe.util.d.ts

@@ -1,13 +1,35 @@
 /**
  * Utility functions for iframe full screen mode positioning
  */
+/**
+ * Marker class on `SectionItemModal`'s scrollable body. A section canvas rendered in that
+ * modal (presentation tools, DynamicContent's section preview, SectionList/ContentList item
+ * modals) is NOT inside the deck's content box, so a full-screen embeddable must size itself
+ * against the modal body instead — see `positionFullScreenIframe`.
+ */
+export declare const SECTION_MODAL_CONTENT_SELECTOR = ".section-item-modal__content";
 export interface FullScreenPositionOptions {
     container: HTMLElement;
     canvasContentSelector?: string;
+    /** Ancestor that, when present, owns the geometry instead of the deck content box. */
+    modalContentSelector?: string;
 }
 /**
- * Positions an iframe container in full screen mode
- * Calculates height from current position to bottom of parent window
+ * Positions an iframe container in full screen mode.
+ *
+ * Two hosts, two coordinate systems (PIT-8147):
+ *
+ * - **Deck** — the component renders inside the running presentation, so the container is
+ *   pinned (`fixed`) to the deck content box and stretched to the bottom of the window.
+ * - **Section modal** — the component renders in `SectionItemModal`, an overlay ON TOP of the
+ *   deck. Copying the deck's box there lands the app under the modal's dead space (offset
+ *   right/down) and runs it past the modal body's bottom edge, where `overflow-auto` clips it.
+ *   `fixed` is wrong twice over: while the modal panel slides in or out it carries a `transform`,
+ *   which makes it the containing block for fixed descendants, so "viewport" coordinates flip
+ *   meaning between mid-slide and at rest. The modal body IS the
+ *   full-screen surface, so stay in flow and take exactly its height — no coordinates to get
+ *   wrong, and the modal's own max-width/centering keeps applying. `relative` is kept so the
+ *   container still anchors its own absolutely positioned children (the loading overlay).
  */
 export declare function positionFullScreenIframe(options: FullScreenPositionOptions): void;
 /**

package/lib/apps/canvas-builder/util/iframe.util.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/apps/canvas-builder/util/lazySections.util.d.ts

@@ -0,0 +1,35 @@
+import { CanvasSection } from '../../../../types/openapi';
+/**
+ * Helpers for opt-in lazy section loading (`?lazy_sections=true`, PIT-7073).
+ *
+ * A lazy shell response carries ordered `section_ids` plus lightweight section
+ * STUBS — `{ id, name, thumbnail_url, metadata, is_draft, content: { data: [] } }`
+ * — so list views (ToC, section rail) render immediately while the real bodies
+ * stream in via the batch endpoint.
+ */
+/**
+ * A stub carries an empty placeholder `content`; a hydrated body has components.
+ * This is how we tell "not fetched yet" from "fetched".
+ */
+export declare const isHydratedSection: (section?: CanvasSection | null) => boolean;
+/**
+ * Merge an incoming shell's sections over what we already hold, keeping any body
+ * we've already hydrated.
+ *
+ * A shell gets RE-APPLIED constantly: every embedded-app canvas update (each
+ * Shopping Cart change in the PRH apps) round-trips the canvas through the host,
+ * which hands back the lazy shell. Applying it verbatim would wipe the hydrated
+ * bodies, so the deck blanks and visibly BLINKS while it re-fetches them.
+ *
+ * Section bodies are separate canvases, so a deck-level update never invalidates
+ * them — carrying them forward is safe. An incoming section that IS hydrated
+ * always wins, so a genuine section refresh still lands.
+ */
+export declare const preserveHydratedSections: (previous: CanvasSection[] | undefined, incoming: CanvasSection[]) => CanvasSection[];
+/**
+ * The subset of `section_ids` that still needs fetching.
+ *
+ * Without this a re-applied shell would re-download every body on each
+ * interaction — on a 1k-section deck that's a full request storm per cart click.
+ */
+export declare const pendingSectionIds: (sectionIds: string[], sections: CanvasSection[] | undefined) => string[];

package/lib/apps/canvas-builder/util/lazySections.util.test.d.ts

@@ -0,0 +1 @@
+export {};