@pitcher/js-api 1.30.0 → 1.31.0

package/lib/apps/canvas-builder/composables/usePresentationTools.d.ts

@@ -0,0 +1,112 @@
+import { ComputedRef, Ref } from 'vue';
+import { CanvasRetrieve } from '../../../../types/openapi';
+/**
+ * Presentation tools rail (PIT-8031): the instance's embeddable-only section canvases —
+ * the SAME roster the pitchdeck wizard offers (next-core `resolve-embeddable-only-slides`)
+ * — openable as a modal OVER the running deck, independent of deck content.
+ *
+ * This is the decoupled successor to the "hidden section list" workaround: tool
+ * availability no longer requires the tool to be a slide in the deck
+ * (`useInstalledEmbeddables` filters by deck content; this roster deliberately does not).
+ * "Add tool as agenda point" in the wizard stays the way to put a tool INTO the deck/ToC.
+ *
+ * Opt-in via the `canvas.enable_presentation_tools` org/instance setting (default off),
+ * Impact mode only. Both platform surfaces degrade silently: no `coreRestApiAxios` (host
+ * without core API — incl. iOS `file://` apps, which are CORS-jailed for direct core
+ * fetches) or no `fetchCanvas` → the button never appears.
+ */
+export interface PresentationTool {
+    /** The tool's section canvas id. */
+    id: string;
+    name: string;
+    /**
+     * The installed app's `app.json` icon, RAW as stored (`fas fa-building-columns`,
+     * `far fa-browser`, `fa-kit fa-…`, or a bare name) — normalise with `getAppIconProps()`
+     * before handing it to `CIcon`. `null` when the roster could not resolve the app
+     * (uninstalled, or an older endpoint that predates PIT-8274) → render the generic glyph.
+     * The tool canvas's `thumbnail_url` is deliberately NOT carried: it is a screenshot of
+     * the slide, and the overlay shows app icons like every other app surface (PIT-8274).
+     */
+    icon: string | null;
+}
+type CanvasSection = CanvasRetrieve['sections'][number];
+/**
+ * Section ids THIS composable injected into `activeCanvas.sections`. Ids already present
+ * as real deck slides are never added. The one consumer is `closeTool`, which unregisters
+ * them so nothing outlives the modal. (The shortcuts derivation no longer needs the set:
+ * `useInstalledEmbeddables` now filters the sections lookup through the deck's OWN
+ * SectionList/ContentList refs — PIT-8031 QA Q1 — which excludes injected entries by
+ * construction.) Replaced, not mutated, so computeds re-run.
+ */
+export declare const injectedToolSectionIds: Ref<{
+    forEach: (callbackfn: (value: string, value2: string, set: ReadonlySet<string>) => void, thisArg?: any) => void;
+    has: (value: string) => boolean;
+    readonly size: number;
+    entries: () => SetIterator<[string, string]>;
+    keys: () => SetIterator<string>;
+    values: () => SetIterator<string>;
+    union: <U>(other: ReadonlySetLike<U>) => Set<string | U>;
+    intersection: <U>(other: ReadonlySetLike<U>) => Set<string & U>;
+    difference: <U>(other: ReadonlySetLike<U>) => Set<string>;
+    symmetricDifference: <U>(other: ReadonlySetLike<U>) => Set<string | U>;
+    isSubsetOf: (other: ReadonlySetLike<unknown>) => boolean;
+    isSupersetOf: (other: ReadonlySetLike<unknown>) => boolean;
+    isDisjointFrom: (other: ReadonlySetLike<unknown>) => boolean;
+    [Symbol.iterator]: () => SetIterator<string>;
+}, ReadonlySet<string> | {
+    forEach: (callbackfn: (value: string, value2: string, set: ReadonlySet<string>) => void, thisArg?: any) => void;
+    has: (value: string) => boolean;
+    readonly size: number;
+    entries: () => SetIterator<[string, string]>;
+    keys: () => SetIterator<string>;
+    values: () => SetIterator<string>;
+    union: <U>(other: ReadonlySetLike<U>) => Set<string | U>;
+    intersection: <U>(other: ReadonlySetLike<U>) => Set<string & U>;
+    difference: <U>(other: ReadonlySetLike<U>) => Set<string>;
+    symmetricDifference: <U>(other: ReadonlySetLike<U>) => Set<string | U>;
+    isSubsetOf: (other: ReadonlySetLike<unknown>) => boolean;
+    isSupersetOf: (other: ReadonlySetLike<unknown>) => boolean;
+    isDisjointFrom: (other: ReadonlySetLike<unknown>) => boolean;
+    [Symbol.iterator]: () => SetIterator<string>;
+}>;
+/**
+ * Reset ALL module-level state — for test isolation (spec `beforeEach`). Without this,
+ * `toolSectionCache`/`fetchedForInstance`/`selectedTool` survive between cases, so a test
+ * reusing a tool id would silently hit the cache and skip the fetch path it means to cover.
+ */
+export declare function resetPresentationToolsState(): void;
+/**
+ * A tool canvas is a full `CanvasRetrieve`; the deck's section machinery wants the
+ * `CanvasSection` shape. The content tree sits at `sections[0].content.data` when the tool
+ * canvas nests one, else `content.data` (same normalization as DynamicContent's
+ * `getSectionComponents`).
+ */
+export declare function toolCanvasToSection(canvas: CanvasRetrieve): CanvasSection;
+export declare function usePresentationTools(): {
+    tools: ComputedRef<{
+        id: string;
+        name: string;
+        icon: string | null;
+    }[]>;
+    hasSingleTool: ComputedRef<boolean>;
+    shouldShowTools: ComputedRef<boolean>;
+    isFrameless: ComputedRef<boolean>;
+    isFetchingToolSection: ComputedRef<boolean>;
+    selectedTool: ComputedRef<{
+        id: string;
+        name: string;
+        icon: string | null;
+    } | null>;
+    selectedToolSection: ComputedRef<{
+        readonly id: string;
+        name: string;
+        content: Record<string, any>;
+        theme?: (Record<string, any> | null) | undefined;
+        metadata?: Record<string, any> | undefined;
+        is_draft: boolean;
+    } | null>;
+    ensureTools: () => Promise<void>;
+    openTool: (tool: PresentationTool) => Promise<void>;
+    closeTool: () => void;
+};
+export {};

package/lib/apps/canvas-builder/composables/usePresentationTools.spec.d.ts

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

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

@@ -771,6 +771,19 @@ 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

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

@@ -1,4 +1,5 @@
 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";
@@ -7,22 +8,32 @@ export interface ResolveCompletionWizardVariantParams {
     isReactWizardSettingEnabled: boolean;
     /** The React wizard app resolved to a loadable URL (installed or local dev override). */
     isReactWizardAvailable: boolean;
-    /** The deck's admin config uses features the React wizard cannot honor yet (see below). */
-    hasUnsupportedConfig?: 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 — or a deck whose admin config the React wizard cannot honor — falls back
- * to the Vue wizard so no flow is ever lost.
- */
-export declare function resolveCompletionWizardVariant(p: ResolveCompletionWizardVariantParams): 'vue' | 'react';
-/**
- * Admin group_selector config features the React wizard does not implement yet:
- * repetition rules (slide repeats + salesforce-populator data binding) and visibility
- * rules. Decks using them keep the vanilla wizard regardless of the setting.
+ * 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 hasUnsupportedGroupSelectorConfig(context: Record<string, unknown> | null | undefined): boolean;
+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`.
@@ -53,6 +64,191 @@ interface WizardCancelCanvasContext {
     };
 }
 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;
 /**
@@ -104,4 +300,48 @@ export interface ShouldAutoOpenCompletionWizardParams {
  * 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/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-selector/stores/app.d.ts

@@ -12,6 +12,7 @@ export default function useApp(): {
             is_template?: boolean | undefined;
             is_section?: boolean | undefined;
             is_block?: boolean | undefined;
+            is_master?: boolean | undefined;
             is_editable?: boolean | undefined;
             is_default?: boolean | undefined;
             metadata?: any;
@@ -60,6 +61,7 @@ export default function useApp(): {
             is_template?: boolean | undefined;
             is_section?: boolean | undefined;
             is_block?: boolean | undefined;
+            is_master?: boolean | undefined;
             is_editable?: boolean | undefined;
             is_default?: boolean | undefined;
             metadata?: any;
@@ -108,6 +110,7 @@ export default function useApp(): {
             is_template?: boolean | undefined;
             is_section?: boolean | undefined;
             is_block?: boolean | undefined;
+            is_master?: boolean | undefined;
             is_editable?: boolean | undefined;
             is_default?: boolean | undefined;
             metadata?: any;
@@ -156,6 +159,7 @@ export default function useApp(): {
             is_template?: boolean | undefined;
             is_section?: boolean | undefined;
             is_block?: boolean | undefined;
+            is_master?: boolean | undefined;
             is_editable?: boolean | undefined;
             is_default?: boolean | undefined;
             metadata?: any;
@@ -210,6 +214,7 @@ export default function useApp(): {
             is_template?: boolean | undefined;
             is_section?: boolean | undefined;
             is_block?: boolean | undefined;
+            is_master?: boolean | undefined;
             is_editable?: boolean | undefined;
             is_default?: boolean | undefined;
             metadata?: any;
@@ -258,6 +263,7 @@ export default function useApp(): {
             is_template?: boolean | undefined;
             is_section?: boolean | undefined;
             is_block?: boolean | undefined;
+            is_master?: boolean | undefined;
             is_editable?: boolean | undefined;
             is_default?: boolean | undefined;
             metadata?: any;
@@ -306,6 +312,7 @@ export default function useApp(): {
             is_template?: boolean | undefined;
             is_section?: boolean | undefined;
             is_block?: boolean | undefined;
+            is_master?: boolean | undefined;
             is_editable?: boolean | undefined;
             is_default?: boolean | undefined;
             metadata?: any;
@@ -354,6 +361,7 @@ export default function useApp(): {
             is_template?: boolean | undefined;
             is_section?: boolean | undefined;
             is_block?: boolean | undefined;
+            is_master?: boolean | undefined;
             is_editable?: boolean | undefined;
             is_default?: boolean | undefined;
             metadata?: any;
@@ -403,6 +411,7 @@ export default function useApp(): {
         is_template?: boolean | undefined;
         is_section?: boolean | undefined;
         is_block?: boolean | undefined;
+        is_master?: boolean | undefined;
         is_editable?: boolean | undefined;
         is_default?: boolean | undefined;
         metadata?: any;
@@ -450,6 +459,7 @@ export default function useApp(): {
         is_template?: boolean | undefined;
         is_section?: boolean | undefined;
         is_block?: boolean | undefined;
+        is_master?: boolean | undefined;
         is_editable?: boolean | undefined;
         is_default?: boolean | undefined;
         metadata?: any;
@@ -498,6 +508,7 @@ export default function useApp(): {
         is_template?: boolean | undefined;
         is_section?: boolean | undefined;
         is_block?: boolean | undefined;
+        is_master?: boolean | undefined;
         is_editable?: boolean | undefined;
         is_default?: boolean | undefined;
         metadata?: any;
@@ -546,6 +557,7 @@ export default function useApp(): {
         is_template?: boolean | undefined;
         is_section?: boolean | undefined;
         is_block?: boolean | undefined;
+        is_master?: boolean | undefined;
         is_editable?: boolean | undefined;
         is_default?: boolean | undefined;
         metadata?: any;
@@ -594,6 +606,7 @@ export default function useApp(): {
         is_template?: boolean | undefined;
         is_section?: boolean | undefined;
         is_block?: boolean | undefined;
+        is_master?: boolean | undefined;
         is_editable?: boolean | undefined;
         is_default?: boolean | undefined;
         metadata?: any;
@@ -642,6 +655,7 @@ export default function useApp(): {
         is_template?: boolean | undefined;
         is_section?: boolean | undefined;
         is_block?: boolean | undefined;
+        is_master?: boolean | undefined;
         is_editable?: boolean | undefined;
         is_default?: boolean | undefined;
         metadata?: any;

package/lib/apps/collection-player/components/AppHeader.spec.d.ts

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

package/lib/apps/collection-player/composables/speaker-notes.use.d.ts

@@ -0,0 +1,14 @@
+import { Ref } from 'vue';
+import { CollectionSlide } from '../types/collection-player.type';
+/**
+ * Publish the on-screen slide's pptx speaker notes so the Notes App can render them
+ * (PIT-8016). Only `type: 'slide'` entries map onto a pptx page — whole-file entries
+ * (video, image, web) have no slide index, so they clear the key instead.
+ */
+declare const _default: ({ isSwiperVisible, activeSlide, enabled, }: {
+    isSwiperVisible: Ref<boolean>;
+    activeSlide: Ref<CollectionSlide | null>;
+    /** Host opt-in — see `publishSpeakerNotes` on the player's props. */
+    enabled: () => boolean;
+}) => void;
+export default _default;

package/lib/apps/collection-player/composables/speaker-notes.use.spec.d.ts

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

package/lib/apps/collection-player/stores/app.store.d.ts

@@ -45,6 +45,7 @@ type StorePayload = {
     emit: EmitFn<Emit>;
     options?: Options;
     nodeId?: string;
+    showNotesToggle?: ComputedRef<boolean>;
 };
 type StoreData = {
     isLoading: Ref<boolean>;
@@ -81,11 +82,14 @@ type StoreData = {
     cacheNavigation: ReturnType<typeof useCacheNavigation>;
     nodeId?: string;
     handleKeyAction: ActionCallback;
+    /** Show the Notes App toggle in the header — rep surfaces only. Reactive: the host derives
+     *  it from a LaunchDarkly flag, which can flip while the player is open. */
+    showNotesToggle: ComputedRef<boolean>;
     annotationLayer: ReturnType<typeof useAnnotationLayer>;
     updateSlideInSwiper: (index: number) => void;
     ensureActiveSlideInView: () => void;
     rootElement: Ref<HTMLElement | null>;
 };
-export declare function provideAppStore({ data, isEditMode, rootElement, api, emit, options, isLoading, nodeId, inModal, }: StorePayload): StoreData;
+export declare function provideAppStore({ data, isEditMode, rootElement, api, emit, options, isLoading, nodeId, inModal, showNotesToggle, }: StorePayload): StoreData;
 export declare function useAppStore(): StoreData;
 export {};

package/lib/apps/collection-player/stores/showNotesToggle.spec.d.ts

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