@vosjs/studio-core 0.24.1 → 0.25.0

package/dist/index.d.ts

@@ -1894,6 +1894,126 @@ type Media = ProjectDoc['source'] & {
     frame?: MediaFrame;
 };
 
+/**
+ * The callout grammar — three shapes a viewer learns once, composed from the
+ * product's own register so the card is unmistakably the video's and still
+ * the product's.
+ *
+ * The rule set (the distinguishability principle: share the product's hue
+ * and type, contrast in value, elevation, scale and place):
+ *  - VALUE INVERSION: a light app gets a dark card in the product's hue, a
+ *    dark app a light one; the accent is kept for the kicker and the dot.
+ *  - ELEVATION: a real shadow plus a hairline of light on the edge.
+ *  - SCALE: the title is set for the render, CALLOUT_TYPE_RATIO times the
+ *    app's body as it appears on screen at the layer's start (the camera
+ *    scales the app, so the caller passes that scale), never the app's own
+ *    size.
+ *  - MOTION: a rise in, a fade out.
+ *  - PLACE is the pin's (lower/pin.ts), not the card's.
+ *
+ * Pure: hex in, markup and CSS out. The starters are this grammar in the
+ * house register; `vos callout` is it in the take's BRAND.md.
+ */
+
+type CalloutShape = 'tag' | 'note' | 'code';
+declare const CALLOUT_SHAPES: readonly CalloutShape[];
+/** The title's size over the app's body size as seen on screen. */
+declare const CALLOUT_TYPE_RATIO = 1.35;
+/** The app's body size when nothing says otherwise (CSS px at the viewport). */
+declare const CALLOUT_DEFAULT_BODY_PX = 14;
+/** The product's register: what a card shares with the app. */
+interface CalloutRegister {
+    /** The app's ground (its page background), a hex. Decides the inversion. */
+    ground: string;
+    /** The product's accent, a hex: the kicker, the dot, the bar. */
+    accent: string;
+    /** The words face: a hosted catalog family or a system stack. */
+    face?: string;
+    /** The code face. */
+    mono?: string;
+    /** The app's body type size in CSS px at the recorded viewport. */
+    body?: number;
+}
+interface CalloutWords {
+    /** A short label above the title, set in the accent (a tag is only this). */
+    kicker?: string;
+    title?: string;
+    /** One or two lines under the title. */
+    body?: string;
+    /** The payload, kept as typed (lines break on \n). */
+    code?: string;
+}
+/** The resolved look: colours and sizes in design px. */
+interface CalloutLook {
+    light: boolean;
+    cardGround: string;
+    cardInk: string;
+    cardMuted: string;
+    hairline: string;
+    accent: string;
+    shadow: string;
+    face: string;
+    mono: string;
+    kickerPx: number;
+    titlePx: number;
+    bodyPx: number;
+    codePx: number;
+    radius: number;
+    padX: number;
+    padY: number;
+}
+declare const HOUSE_REGISTER: CalloutRegister;
+/**
+ * Resolve a register into a look. `scale` is design px per CSS px of the
+ * app as it appears at the layer's start (the card's footage scale times
+ * the camera's level); 1 when unknown.
+ */
+declare function calloutLook(register: CalloutRegister, scale?: number): CalloutLook;
+interface CalloutBox {
+    width: number;
+    height: number;
+}
+/**
+ * The design box a shape needs for its words: one line for a tag, the
+ * kicker, title and wrapped body for a note, the lines for code. Widths
+ * estimate glyphs at 0.56 em for words and 0.62 em for mono.
+ */
+declare function calloutBox(shape: CalloutShape, look: CalloutLook, words: CalloutWords): CalloutBox;
+/** The markup and CSS for a shape in a look, sized to a box. */
+declare function calloutSource(shape: CalloutShape, look: CalloutLook, words: CalloutWords, box: CalloutBox): {
+    html: string;
+    css: string;
+};
+interface CalloutClipOptions {
+    id: string;
+    /** OUTPUT seconds. */
+    start: number;
+    duration: number;
+    /** Design px per CSS px of the app on screen at `start` (1 = unknown). */
+    scale?: number;
+    pin?: OverlayPin;
+    /** The fallback place when the pin cannot resolve (frame fractions). */
+    at?: {
+        x: number;
+        y: number;
+    };
+}
+/** A callout as an html overlay clip: the grammar applied to a register. */
+declare function calloutClip(shape: CalloutShape, register: CalloutRegister, words: CalloutWords, opts: CalloutClipOptions): HtmlOverlayClip;
+/**
+ * The card's ground as its CSS declares it (the root rule's background),
+ * for the picture check that compares it with the footage it covers. Null
+ * when the CSS names none in a form a hex can be read from.
+ */
+declare function calloutGroundOf(css: string): string | null;
+type Rgb = [number, number, number];
+declare function hexToRgb(hex: string): Rgb | null;
+declare function rgbToHex([r, g, b]: Rgb): string;
+declare function parseCssColour(s: string): Rgb | null;
+declare function relativeLuminance([r, g, b]: Rgb): number;
+/** CIE76 colour difference between two sRGB colours. */
+declare function deltaE(a: Rgb, b: Rgb): number;
+
 /**
  * Capture-space normalization — the single seam that makes window/monitor
  * recordings look like tab recordings to everything downstream.
@@ -2992,6 +3112,19 @@ interface PinReferent {
  * second. A `rect` is taken as written. Null when nothing names a rect.
  */
 declare function pinReferent(doc: ProjectDoc, pin: OverlayPin): PinReferent | null;
+/** A step a layer could be pinned to: it has an element, and its window overlaps the layer's. */
+interface PinCandidate {
+    step: string | number;
+    do: string;
+    selector?: string;
+    /** The step's OUTPUT window. */
+    output: {
+        start: number;
+        end: number;
+    };
+    /** Seconds of the layer's window the step's covers. */
+    overlap: number;
+}
 /** The step a pin names: its id first, then its record-time index. */
 declare function findStep(steps: readonly StepSpan[], ref: string | number): StepSpan | undefined;
 /**
@@ -3299,6 +3432,16 @@ declare function docZoomTrack(input: ProjectDoc): KeyframeTrack<number[]> | unde
  * and the layer keeps its `transform` — the lint says why.
  */
 declare function resolvePins(doc: ProjectDoc, layout: CardLayout, camera: CameraModel, zoomTrack: KeyframeTrack<number[]> | undefined): Map<string, PinPlacement>;
+/**
+ * The steps an unpinned layer could name: every step with an element (a
+ * rect, or presses inside its window) whose output window overlaps the
+ * layer's, most overlap first. The studio's Pin-to select and the lint's
+ * advice read this.
+ */
+declare function pinCandidates(doc: ProjectDoc, clip: {
+    start: number;
+    duration: number;
+}): PinCandidate[];
 /**
  * A pinned layer's effective [x, y, scale, rotation, opacity] at CLIP-LOCAL
  * time t — the host-side mirror the picking layer substitutes into the
@@ -3645,22 +3788,8 @@ declare function htmlLayerPayload(clip: HtmlOverlayClip): {
     html: HtmlLayerPayload;
 };
 
-/**
- * The house starters for an HTML layer: what one press of the studio's HTML
- * verb puts on the canvas, and what its panel's Starter select swaps in.
- * Product defaults the way the three text presets are (code, not shelf
- * data), five and not fifty: a LIBRARY of components is an official project
- * on the shelf that an agent applies as a template.
- *
- * Each is real, readable markup and CSS a person can retune, in the house
- * look (a dark card, Inter for words, JetBrains Mono for code, both hosted so
- * the faces resolve from the CSS alone), with a `box-shadow` so the derived
- * bleed is exercised. `htmlStarters.test.ts` proves every one passes the
- * gate with no problem and no warning.
- */
-
 interface HtmlStarter {
-    id: 'callout' | 'code' | 'terminal' | 'keys' | 'badge';
+    id: 'note' | 'tag' | 'code' | 'terminal' | 'keys' | 'badge';
     name: string;
     html: string;
     css: string;
@@ -4694,4 +4823,4 @@ declare function rejectSpan(rejected: RejectedSpan[] | undefined, lane: Rejected
     anchor?: StepAnchor;
 }, note?: string): RejectedSpan;
 
-export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, type Anim, type AnimKind, type AnimSide, type AnimStep, type AppliedTemplate, type ApplyTemplateOptions, type AspectRatioOption, type AudioClip, type AudioPlanPoint, type AudioPlanTrack, BACKGROUND_Z, BASE_FRAME_STYLE, type Backdrop, type BackgroundMedia, type BakedText3dAsset, type BakedText3dMaterial, type BrowserBarStyle, type BuildDigestInput, CAMERA_CENTRE_RAMP, CAMERA_COVER_MIN, CAMERA_FAR, CAMERA_NEAR, CAM_CHAIN_GAP, CAM_EASE, CAM_PAN, CAM_PAN_EASE, CAM_RAMP_IN, CAM_RAMP_OUT, CAM_SIZE_MAX, CAM_SIZE_MIN, CAM_SPAN_MIN, CAPTURE_COVERAGE_MIN, CARD_EDGE_OVERDRAW, CARD_ENTER_KINDS, CARD_EXIT_KINDS, CARD_FADE_SECONDS, CARD_FOV, CARD_Z, CHANNEL_SPECS_HASH, CHANNEL_SPECS_VERIFIED, CLICK_FX_INTENSITY, CLICK_FX_PRE, CLICK_HIGHLIGHT_FADE, CLICK_PAIR_MAX, CLICK_PULSE_DUR, CLICK_RECT_MAX_FRAC, CLICK_RIPPLE_DUR, CLICK_SYNTH_RELEASE, CROP_MAX_PX, CROP_MIN_FRAC, CROP_MIN_PX, CROP_PAD, CURSOR_IDLE_EPS_FRAC, CURSOR_IDLE_FADE_IN, CURSOR_IDLE_FADE_OUT, CURSOR_IDLE_HOLD, type CamBubbleRect, type CamPoseSpan, type CamStyle, type CameraModel, type CaptureNormalization, type CardLayout, type ClickFxStyle, type CopiedLayout, type CopyLayoutOptions, type CopyStyleOptions, type CursorEvent, type CursorFadeKey, type CursorIdleOptions, type CursorStyle, type CursorTrack, DARK_GROUND, DEFAULT_BROWSER_BAR, DEFAULT_CAM_POSE, DEFAULT_CAM_STYLE, DEFAULT_CLICK_FX, DEFAULT_CURSOR_STYLE, DEFAULT_DUCK, DEFAULT_FRAME_STYLE, DEFAULT_SPEED_PARAMS, DEFAULT_TILT_POSE, DEFAULT_ZOOM_LEVEL, DEFAULT_ZOOM_STYLE, DESIGN_FRAME_WIDTH, DESTINATIONS, DIGEST_CROP_MAX, DIGEST_FULL_MAX, DIGEST_VERSION, DOC_SCHEMA_VERSION, DRAG_FIT_LEVEL, DRAG_MIN_S, DRAG_MIN_TRAVEL_FRAC, type Destination, type Digest, type DigestImageRef, type DigestPlan, type DigestTakeFacts, type DocSegment, type Drag, type DuckOptions, END_CARD_FROM, END_CARD_RECEDE, END_CARD_SECONDS, ENTRANCE_SECONDS, EXPORT_RESOLUTION_OPTIONS, EXPORT_SHORT_EDGE, type EndCard, type EnvelopePoint, type ExportResolution, type ExtractClickOptions, FOLLOW_RECENTER, FOLLOW_SAFE_RATIO, FRAME_BORDER_COLOR_DEFAULT, FRAME_BORDER_DEFAULT, FRAME_BORDER_WIDTH_DEFAULT, FREEZE_DEFAULT_SECONDS, FREEZE_SECONDS_MAX, FREEZE_SECONDS_MIN, type FocusBounds, type FollowEvent, type FollowOptions, type FrameEntrance, type FrameGeometry, type FrameStyle, type FreezeExtent, type FreezeSpan, HOUSE_GRADIENT, HTML_LAYER_FOREIGN_FIELDS, HTML_LAYER_MAX_BYTES, HTML_LAYER_SVG_CODE, HTML_LAYER_WARN_BYTES, HTML_STARTERS, type HtmlLayerFace, type HtmlLayerInlineFace, type HtmlLayerPayload, type HtmlLayerProblem, type HtmlLayerProblemCode, type HtmlLayerSource, type HtmlOverlayClip, type HtmlOverlayFont, type HtmlStarter, IDLE_KINDS, type IdleKind, type IngestOptions, LAYER_CARD_SHADOW, LAYOUT_FRAME_FIELDS, LOOK_KINDS, type LayerCard, type LayoutParts, type Look, type LookBrand, type LookKind, type LookPlacement, type LowerProgramOptions, type LoweredAudioClip, type LoweredClick, type LoweredComposition, type LoweredZoomSpan, MEDIA_ENTER_KINDS, MEDIA_EXIT_KINDS, MEDIA_FRAME_KEYS, MEDIA_KEY_PREFIX, MINIMAL_BAR_THEMES, MOTION_DELTA, MOTION_EASE, type Media, type MediaFrame, type MediaFrameKey, type MediaOverlayClip, type MediaSegment, type MicRms, type MinimalBarTheme, type Moment, type MomentKind, type MomentsOptions, type MotionKey, type MotionPose, type MotionPose3D, type MusicBedInput, type NormRect, OBJECT_DEFAULT_SCALE, OVERLAY_FONT_FACES, OVERLAY_LINE_HEIGHT, OVERLAY_MEDIA_DEFAULT_RADIUS, OVERLAY_MEDIA_DEFAULT_WIDTH, OVERLAY_MIN_DURATION, OVERLAY_SCALE_MAX, OVERLAY_SIZE_MAX, OVERLAY_SIZE_MIN, OVERLAY_TRANSITION_DUR, OVERLAY_Z, type ObjectAnimation, type ObjectAsset, type ObjectClip, type ObjectPrimitiveShape, type OverlayClip, type OverlayFontFace, type OverlayKind, type OverlayPin, type OverlayPresetStyle, type OverlayRect, type OverlayTransform, type OverlayTransition, PIN_GAP, PIN_MARGIN, PLATE_GROUND, PLAYBACK_ACTIVITY, PRIMARY_MEDIA, PROGRAM_RETIME, type PinCarry, type PinMark, type PinPlacement, type PinPlacementInput, type PinReferent, type PinSide, type PinSideResolved, type PlanOptions, type PlanTiltOptions, type PlaneSize, type ProgramAnchorDoc, type ProgramTweenEdit, type ProjectDoc, type PxRect, REJECT_OVERLAP, REST_TILT_ID, type RecordingArtifact, type RecordingMeta, type Rect, type RejectedLane, type RejectedSpan, type ResolvedOverlayBox, type ResolvedOverlayStyle, SCENE_MOTION, SCENE_QUIET, SEGMENT_ENTER_KINDS, SEGMENT_EXIT_KINDS, SPEED_RATE_MAX, SPEED_RATE_MIN, SPEED_SPAN_MIN, STAGE_CLIP_PREFIX, STILL_DEFAULT, STUDIO_ENTRY_ID, STYLE_FIELDS, type SegmentExtent, type SmoothOptions, type SmoothPoint, type SpeedParams, type SpeedSpan, type StepAnchor, type StepSpan, type StudioAudioPlan, type StudioDoc, type StudioEntry, type StyleField, TEXT3D_DEPTH_DEFAULT, TEXT3D_DEPTH_MAX, TEXT3D_DEPTH_MIN, TEXT_ENTER_KINDS, TEXT_EXIT_KINDS, TEXT_PRESETS, TILT_AUTO_DEAD_ZONE, TILT_AUTO_MIN, TILT_CHAIN_GAP, TILT_DEG_MAX, TILT_EASE, TILT_INTENSITY_MAX, TILT_PAN, TILT_PAN_EASE, TILT_RAMP_IN, TILT_RAMP_OUT, TILT_SPAN_MIN, TILT_UI_DEG_MAX, TRANSITION_SECONDS, TRANSITION_SECONDS_MAX, TRANSITION_SECONDS_MIN, TRANSITION_SPEED_MULT, type TemplateAnchor, type Text3dMaterial, type TextFxDirection, type TextFxKind, type TextFxSpec, type TextFxUnit, type TextOverlayBox, type TextOverlayClip, type TextOverlayPreset, type TextOverlayStroke, type TiltPersonality, type TiltSpan, type TiltStyleName, type TranscriptSegment, type Transition, type TransitionKind, type TransitionMove, type TransitionOut, type TransitionSpeed, WINDOW_FOCUS_MIN, ZOOM_CHAIN_GAP, ZOOM_EASE, ZOOM_LEVELS, ZOOM_LEVEL_MAX, ZOOM_LEVEL_MIN, ZOOM_PAN, ZOOM_PAN_EASE, ZOOM_RAMP_IN, ZOOM_RAMP_IN_OVERLAP, ZOOM_RAMP_OUT, ZOOM_SPAN_MIN, ZOOM_STYLES, ZOOM_STYLE_OPTIONS, type ZoomSpan, type ZoomStyleName, type ZoomStyleParams, type ZoomView, type ZoomWindow, anchorKindOf, anchorSourceDuration, animStep, applyLook, applyTemplate, aspectRatioValue, audioLane, backdropMedia, buildDigest, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cameraCentring, cameraModel, cardEnter, cardExit, cardFields, cardInset, cardPointToScreen, cardPoseTrack, clampCamFrac, clampCamSize, clampFocus, clampFreezeSeconds, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipLength, clipsFrom, computeCardLayout, computeMicRms, computePeaks, copyLayout, copyStyle, cropBox, cssFamilies, cssWeights, cursorIdleFade, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docFreezes, docMediaList, docOutputDuration, docRestTime, docStillTime, docToCropSpace, docToFullSpace, docTransitions, docZoomTrack, dragsFromTrack, dropTemplate, duckCurve, effectiveSegments, endCardClips, enterKey, enterOf, entranceSeconds, envelopeAt, envelopeValueAt, exitKey, exitOf, exitSeconds, expandEndCard, expectedFrameSize, exportSizeFor, extractClicks, findStep, focusBounds, focusForViewportCentre, followFocusEvents, frameGeometry, freezeLane, freezeOutputExtents, hexToRgbTriplet, houseLook, htmlLayerBleed, htmlLayerBleedFor, htmlLayerFaces, htmlLayerKey, htmlLayerLabel, htmlLayerPayload, htmlLayerPictureBox, htmlLayerProblems, htmlLayerSvg, htmlLayerText, htmlLayerUnhostedFamilies, htmlLayerWidth, htmlStarterClip, idleGaps, idleKey, isKeyedOverlay, isLookKind, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, isRejected, isStageClip, isUnitStep, lastLayerEnd, layerMedia, layoutOf, levelForFocusFraction, lookFromBrand, lookKindForGround, lowerProgramDoc, lowerStudioDoc, lowerToComposition, mediaAtOutput, mediaDuration, mediaFrame, mediaKey, mediaRef, mediaRefId, mediaSource, micLane, migrateHostedDoc, migrateMotion, momentsFromDoc, motionTrack, musicBedClip, nextMediaId, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputEnd, outputRangeToSource, overlapFraction, overlayFaceFor, overlayFontFaces, overlayFontString, overlayFxSpec, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayPinPoseAt, overlayRect, overlaysLane, ownFreezes, pageDisplayUrl, parsePoseId, pickStyle, pinBox, pinPlacement, pinRectOnScreen, pinReferent, pinReferentAt, placeFreezes, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, resolvePins, resolveText3dAsset, resolveZoomStyle, restLeanOf, restSpansThroughTransitions, sameMedia, sceneChanges, scrollRuns, segmentOutputExtents, outputLen as segmentOutputLen, segmentStarts, setSpeedInRange, slideSide, smoothCursor, spanOutputExtent, speedLane, studioAudioPlan, studioEntry, studioLayerData, tiltLane, tiltTrackFromDoc, transitionMult, transitionSeconds, videoLane, voiceKey, wellFormedXml, withBackdrop, withFreezes, withHolds, withoutRejected, wrapProgramLength, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomView, zoomViewport, zoomWindow };
+export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, type Anim, type AnimKind, type AnimSide, type AnimStep, type AppliedTemplate, type ApplyTemplateOptions, type AspectRatioOption, type AudioClip, type AudioPlanPoint, type AudioPlanTrack, BACKGROUND_Z, BASE_FRAME_STYLE, type Backdrop, type BackgroundMedia, type BakedText3dAsset, type BakedText3dMaterial, type BrowserBarStyle, type BuildDigestInput, CALLOUT_DEFAULT_BODY_PX, CALLOUT_SHAPES, CALLOUT_TYPE_RATIO, CAMERA_CENTRE_RAMP, CAMERA_COVER_MIN, CAMERA_FAR, CAMERA_NEAR, CAM_CHAIN_GAP, CAM_EASE, CAM_PAN, CAM_PAN_EASE, CAM_RAMP_IN, CAM_RAMP_OUT, CAM_SIZE_MAX, CAM_SIZE_MIN, CAM_SPAN_MIN, CAPTURE_COVERAGE_MIN, CARD_EDGE_OVERDRAW, CARD_ENTER_KINDS, CARD_EXIT_KINDS, CARD_FADE_SECONDS, CARD_FOV, CARD_Z, CHANNEL_SPECS_HASH, CHANNEL_SPECS_VERIFIED, CLICK_FX_INTENSITY, CLICK_FX_PRE, CLICK_HIGHLIGHT_FADE, CLICK_PAIR_MAX, CLICK_PULSE_DUR, CLICK_RECT_MAX_FRAC, CLICK_RIPPLE_DUR, CLICK_SYNTH_RELEASE, CROP_MAX_PX, CROP_MIN_FRAC, CROP_MIN_PX, CROP_PAD, CURSOR_IDLE_EPS_FRAC, CURSOR_IDLE_FADE_IN, CURSOR_IDLE_FADE_OUT, CURSOR_IDLE_HOLD, type CalloutBox, type CalloutClipOptions, type CalloutLook, type CalloutRegister, type CalloutShape, type CalloutWords, type CamBubbleRect, type CamPoseSpan, type CamStyle, type CameraModel, type CaptureNormalization, type CardLayout, type ClickFxStyle, type CopiedLayout, type CopyLayoutOptions, type CopyStyleOptions, type CursorEvent, type CursorFadeKey, type CursorIdleOptions, type CursorStyle, type CursorTrack, DARK_GROUND, DEFAULT_BROWSER_BAR, DEFAULT_CAM_POSE, DEFAULT_CAM_STYLE, DEFAULT_CLICK_FX, DEFAULT_CURSOR_STYLE, DEFAULT_DUCK, DEFAULT_FRAME_STYLE, DEFAULT_SPEED_PARAMS, DEFAULT_TILT_POSE, DEFAULT_ZOOM_LEVEL, DEFAULT_ZOOM_STYLE, DESIGN_FRAME_WIDTH, DESTINATIONS, DIGEST_CROP_MAX, DIGEST_FULL_MAX, DIGEST_VERSION, DOC_SCHEMA_VERSION, DRAG_FIT_LEVEL, DRAG_MIN_S, DRAG_MIN_TRAVEL_FRAC, type Destination, type Digest, type DigestImageRef, type DigestPlan, type DigestTakeFacts, type DocSegment, type Drag, type DuckOptions, END_CARD_FROM, END_CARD_RECEDE, END_CARD_SECONDS, ENTRANCE_SECONDS, EXPORT_RESOLUTION_OPTIONS, EXPORT_SHORT_EDGE, type EndCard, type EnvelopePoint, type ExportResolution, type ExtractClickOptions, FOLLOW_RECENTER, FOLLOW_SAFE_RATIO, FRAME_BORDER_COLOR_DEFAULT, FRAME_BORDER_DEFAULT, FRAME_BORDER_WIDTH_DEFAULT, FREEZE_DEFAULT_SECONDS, FREEZE_SECONDS_MAX, FREEZE_SECONDS_MIN, type FocusBounds, type FollowEvent, type FollowOptions, type FrameEntrance, type FrameGeometry, type FrameStyle, type FreezeExtent, type FreezeSpan, HOUSE_GRADIENT, HOUSE_REGISTER, HTML_LAYER_FOREIGN_FIELDS, HTML_LAYER_MAX_BYTES, HTML_LAYER_SVG_CODE, HTML_LAYER_WARN_BYTES, HTML_STARTERS, type HtmlLayerFace, type HtmlLayerInlineFace, type HtmlLayerPayload, type HtmlLayerProblem, type HtmlLayerProblemCode, type HtmlLayerSource, type HtmlOverlayClip, type HtmlOverlayFont, type HtmlStarter, IDLE_KINDS, type IdleKind, type IngestOptions, LAYER_CARD_SHADOW, LAYOUT_FRAME_FIELDS, LOOK_KINDS, type LayerCard, type LayoutParts, type Look, type LookBrand, type LookKind, type LookPlacement, type LowerProgramOptions, type LoweredAudioClip, type LoweredClick, type LoweredComposition, type LoweredZoomSpan, MEDIA_ENTER_KINDS, MEDIA_EXIT_KINDS, MEDIA_FRAME_KEYS, MEDIA_KEY_PREFIX, MINIMAL_BAR_THEMES, MOTION_DELTA, MOTION_EASE, type Media, type MediaFrame, type MediaFrameKey, type MediaOverlayClip, type MediaSegment, type MicRms, type MinimalBarTheme, type Moment, type MomentKind, type MomentsOptions, type MotionKey, type MotionPose, type MotionPose3D, type MusicBedInput, type NormRect, OBJECT_DEFAULT_SCALE, OVERLAY_FONT_FACES, OVERLAY_LINE_HEIGHT, OVERLAY_MEDIA_DEFAULT_RADIUS, OVERLAY_MEDIA_DEFAULT_WIDTH, OVERLAY_MIN_DURATION, OVERLAY_SCALE_MAX, OVERLAY_SIZE_MAX, OVERLAY_SIZE_MIN, OVERLAY_TRANSITION_DUR, OVERLAY_Z, type ObjectAnimation, type ObjectAsset, type ObjectClip, type ObjectPrimitiveShape, type OverlayClip, type OverlayFontFace, type OverlayKind, type OverlayPin, type OverlayPresetStyle, type OverlayRect, type OverlayTransform, type OverlayTransition, PIN_GAP, PIN_MARGIN, PLATE_GROUND, PLAYBACK_ACTIVITY, PRIMARY_MEDIA, PROGRAM_RETIME, type PinCandidate, type PinCarry, type PinMark, type PinPlacement, type PinPlacementInput, type PinReferent, type PinSide, type PinSideResolved, type PlanOptions, type PlanTiltOptions, type PlaneSize, type ProgramAnchorDoc, type ProgramTweenEdit, type ProjectDoc, type PxRect, REJECT_OVERLAP, REST_TILT_ID, type RecordingArtifact, type RecordingMeta, type Rect, type RejectedLane, type RejectedSpan, type ResolvedOverlayBox, type ResolvedOverlayStyle, type Rgb, SCENE_MOTION, SCENE_QUIET, SEGMENT_ENTER_KINDS, SEGMENT_EXIT_KINDS, SPEED_RATE_MAX, SPEED_RATE_MIN, SPEED_SPAN_MIN, STAGE_CLIP_PREFIX, STILL_DEFAULT, STUDIO_ENTRY_ID, STYLE_FIELDS, type SegmentExtent, type SmoothOptions, type SmoothPoint, type SpeedParams, type SpeedSpan, type StepAnchor, type StepSpan, type StudioAudioPlan, type StudioDoc, type StudioEntry, type StyleField, TEXT3D_DEPTH_DEFAULT, TEXT3D_DEPTH_MAX, TEXT3D_DEPTH_MIN, TEXT_ENTER_KINDS, TEXT_EXIT_KINDS, TEXT_PRESETS, TILT_AUTO_DEAD_ZONE, TILT_AUTO_MIN, TILT_CHAIN_GAP, TILT_DEG_MAX, TILT_EASE, TILT_INTENSITY_MAX, TILT_PAN, TILT_PAN_EASE, TILT_RAMP_IN, TILT_RAMP_OUT, TILT_SPAN_MIN, TILT_UI_DEG_MAX, TRANSITION_SECONDS, TRANSITION_SECONDS_MAX, TRANSITION_SECONDS_MIN, TRANSITION_SPEED_MULT, type TemplateAnchor, type Text3dMaterial, type TextFxDirection, type TextFxKind, type TextFxSpec, type TextFxUnit, type TextOverlayBox, type TextOverlayClip, type TextOverlayPreset, type TextOverlayStroke, type TiltPersonality, type TiltSpan, type TiltStyleName, type TranscriptSegment, type Transition, type TransitionKind, type TransitionMove, type TransitionOut, type TransitionSpeed, WINDOW_FOCUS_MIN, ZOOM_CHAIN_GAP, ZOOM_EASE, ZOOM_LEVELS, ZOOM_LEVEL_MAX, ZOOM_LEVEL_MIN, ZOOM_PAN, ZOOM_PAN_EASE, ZOOM_RAMP_IN, ZOOM_RAMP_IN_OVERLAP, ZOOM_RAMP_OUT, ZOOM_SPAN_MIN, ZOOM_STYLES, ZOOM_STYLE_OPTIONS, type ZoomSpan, type ZoomStyleName, type ZoomStyleParams, type ZoomView, type ZoomWindow, anchorKindOf, anchorSourceDuration, animStep, applyLook, applyTemplate, aspectRatioValue, audioLane, backdropMedia, buildDigest, calloutBox, calloutClip, calloutGroundOf, calloutLook, calloutSource, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cameraCentring, cameraModel, cardEnter, cardExit, cardFields, cardInset, cardPointToScreen, cardPoseTrack, clampCamFrac, clampCamSize, clampFocus, clampFreezeSeconds, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipLength, clipsFrom, computeCardLayout, computeMicRms, computePeaks, copyLayout, copyStyle, cropBox, cssFamilies, cssWeights, cursorIdleFade, deltaE, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docFreezes, docMediaList, docOutputDuration, docRestTime, docStillTime, docToCropSpace, docToFullSpace, docTransitions, docZoomTrack, dragsFromTrack, dropTemplate, duckCurve, effectiveSegments, endCardClips, enterKey, enterOf, entranceSeconds, envelopeAt, envelopeValueAt, exitKey, exitOf, exitSeconds, expandEndCard, expectedFrameSize, exportSizeFor, extractClicks, findStep, focusBounds, focusForViewportCentre, followFocusEvents, frameGeometry, freezeLane, freezeOutputExtents, hexToRgb, hexToRgbTriplet, houseLook, htmlLayerBleed, htmlLayerBleedFor, htmlLayerFaces, htmlLayerKey, htmlLayerLabel, htmlLayerPayload, htmlLayerPictureBox, htmlLayerProblems, htmlLayerSvg, htmlLayerText, htmlLayerUnhostedFamilies, htmlLayerWidth, htmlStarterClip, idleGaps, idleKey, isKeyedOverlay, isLookKind, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, isRejected, isStageClip, isUnitStep, lastLayerEnd, layerMedia, layoutOf, levelForFocusFraction, lookFromBrand, lookKindForGround, lowerProgramDoc, lowerStudioDoc, lowerToComposition, mediaAtOutput, mediaDuration, mediaFrame, mediaKey, mediaRef, mediaRefId, mediaSource, micLane, migrateHostedDoc, migrateMotion, momentsFromDoc, motionTrack, musicBedClip, nextMediaId, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputEnd, outputRangeToSource, overlapFraction, overlayFaceFor, overlayFontFaces, overlayFontString, overlayFxSpec, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayPinPoseAt, overlayRect, overlaysLane, ownFreezes, pageDisplayUrl, parseCssColour, parsePoseId, pickStyle, pinBox, pinCandidates, pinPlacement, pinRectOnScreen, pinReferent, pinReferentAt, placeFreezes, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, relativeLuminance, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, resolvePins, resolveText3dAsset, resolveZoomStyle, restLeanOf, restSpansThroughTransitions, rgbToHex, sameMedia, sceneChanges, scrollRuns, segmentOutputExtents, outputLen as segmentOutputLen, segmentStarts, setSpeedInRange, slideSide, smoothCursor, spanOutputExtent, speedLane, studioAudioPlan, studioEntry, studioLayerData, tiltLane, tiltTrackFromDoc, transitionMult, transitionSeconds, videoLane, voiceKey, wellFormedXml, withBackdrop, withFreezes, withHolds, withoutRejected, wrapProgramLength, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomView, zoomViewport, zoomWindow };

package/dist/index.js

@@ -236,6 +236,210 @@ var MEDIA_FRAME_KEYS = [
   "focusFollow"
 ];
 
+// src/callout.ts
+var CALLOUT_SHAPES = ["tag", "note", "code"];
+var CALLOUT_TYPE_RATIO = 1.35;
+var CALLOUT_DEFAULT_BODY_PX = 14;
+var HOUSE_REGISTER = {
+  ground: "#ffffff",
+  accent: "#7c3aed"
+};
+var DEFAULT_FACE = "'Inter',-apple-system,system-ui,sans-serif";
+var DEFAULT_MONO = "'JetBrains Mono',ui-monospace,monospace";
+function calloutLook(register, scale = 1) {
+  const ground = hexToRgb(register.ground) ?? [255, 255, 255];
+  const accent = hexToRgb(register.accent) ?? [124, 58, 237];
+  const light = relativeLuminance(ground) > 0.4;
+  const [h, s] = rgbToHsl(accent);
+  const cardGround = light ? hslToHex(h, Math.min(0.35, s * 0.6), 0.07) : hslToHex(h, Math.min(0.25, s * 0.35), 0.97);
+  const bodyPx = register.body ?? CALLOUT_DEFAULT_BODY_PX;
+  const titlePx = Math.max(20, Math.round(CALLOUT_TYPE_RATIO * bodyPx * scale));
+  return {
+    light,
+    cardGround,
+    cardInk: light ? "#fafafa" : "#101012",
+    cardMuted: light ? "rgba(255,255,255,0.64)" : "rgba(16,16,18,0.6)",
+    hairline: light ? "rgba(255,255,255,0.12)" : "rgba(0,0,0,0.1)",
+    accent: rgbToHex(accent),
+    shadow: "0 24px 60px rgba(0,0,0,0.35), 0 2px 6px rgba(0,0,0,0.16)",
+    face: register.face ? quoteFamily(register.face) : DEFAULT_FACE,
+    mono: register.mono ? quoteFamily(register.mono) : DEFAULT_MONO,
+    kickerPx: Math.max(11, Math.round(titlePx * 0.55)),
+    titlePx,
+    bodyPx: Math.max(15, Math.round(titlePx * 0.75)),
+    codePx: Math.max(14, Math.round(titlePx * 0.68)),
+    radius: 16,
+    padX: 24,
+    padY: 20
+  };
+}
+function calloutBox(shape, look, words) {
+  const em = (px, chars, adv) => Math.ceil(px * adv * chars);
+  if (shape === "tag") {
+    const text = words.kicker ?? words.title ?? "";
+    const w = em(look.kickerPx * 1.1, text.length, 0.62) + 14 + 18 * 2;
+    return {
+      width: clamp(w, 120, 720),
+      height: Math.max(36, Math.round(look.kickerPx * 1.1 * 2.6))
+    };
+  }
+  if (shape === "code") {
+    const lines = (words.code ?? "").split("\n");
+    const longest = Math.max(1, ...lines.map((l) => l.length));
+    const lineH = Math.round(look.codePx * 1.7);
+    const w = em(look.codePx, longest, 0.62) + look.padX * 2;
+    const h = lines.length * lineH + look.padY * 2 + (words.kicker ? look.kickerPx * 2 : 0);
+    return { width: clamp(w, 360, 820), height: clamp(h, 72, 640) };
+  }
+  const title = words.title ?? "";
+  const body = words.body ?? "";
+  const titleW = em(look.titlePx, title.length, 0.56);
+  const width = clamp(Math.max(titleW, 320) + look.padX * 2, 360, 640);
+  const inner = width - look.padX * 2;
+  const bodyLines = body ? Math.max(1, Math.ceil(em(look.bodyPx, body.length, 0.54) / inner)) : 0;
+  const titleLines = Math.max(1, Math.ceil(titleW / inner));
+  const height = look.padY * 2 + (words.kicker ? Math.round(look.kickerPx * 1.6) : 0) + titleLines * Math.round(look.titlePx * 1.25) + (bodyLines ? 8 + bodyLines * Math.round(look.bodyPx * 1.5) : 0);
+  return { width, height: clamp(height, 64, 480) };
+}
+function calloutSource(shape, look, words, box) {
+  const base = `box-sizing:border-box;width:${box.width}px;height:${box.height}px;background:${look.cardGround};color:${look.cardInk};border:1px solid ${look.hairline};border-radius:${look.radius}px;box-shadow:${look.shadow};-webkit-font-smoothing:antialiased;`;
+  if (shape === "tag") {
+    const text = esc(words.kicker ?? words.title ?? "");
+    return {
+      html: `<div class="tag"><span class="dot"></span><span class="t">${text}</span></div>`,
+      css: `.tag{font-family:${look.face};display:flex;align-items:center;gap:10px;${base}border-radius:999px;padding:0 18px;background:${look.accent};color:#fff;border-color:rgba(255,255,255,0.18);font-size:${Math.round(look.kickerPx * 1.1)}px;font-weight:600;letter-spacing:0.02em;text-transform:uppercase;white-space:nowrap}.dot{width:8px;height:8px;border-radius:99px;background:#fff;opacity:0.9;flex:none}`
+    };
+  }
+  if (shape === "code") {
+    const lines = (words.code ?? "").split("\n").map(
+      (l) => /^\s*(\/\/|#|\$)/.test(l) ? `<span class="mut">${esc(l)}</span>` : esc(l)
+    ).join("\n");
+    const kicker2 = words.kicker ? `<div class="k">${esc(words.kicker)}</div>` : "";
+    return {
+      html: `<div class="code">${kicker2}<pre class="p">${lines}</pre></div>`,
+      css: `.code{font-family:${look.mono};${base}padding:${look.padY}px ${look.padX}px;font-size:${look.codePx}px;line-height:1.7;letter-spacing:-0.01em}.k{font-family:${look.face};font-size:${look.kickerPx}px;font-weight:600;letter-spacing:0.08em;text-transform:uppercase;color:${look.accent};margin:0 0 ${Math.round(look.kickerPx * 0.9)}px}.p{margin:0;white-space:pre;font:inherit}.mut{color:${look.cardMuted}}`
+    };
+  }
+  const kicker = words.kicker ? `<div class="k"><span class="dot"></span>${esc(words.kicker)}</div>` : "";
+  const body = words.body ? `<div class="b">${esc(words.body)}</div>` : "";
+  return {
+    html: `<div class="note">${kicker}<div class="t">${esc(words.title ?? "")}</div>${body}</div>`,
+    css: `.note{font-family:${look.face};${base}padding:${look.padY}px ${look.padX}px;display:flex;flex-direction:column;justify-content:center}.k{display:flex;align-items:center;gap:8px;font-size:${look.kickerPx}px;font-weight:600;letter-spacing:0.08em;text-transform:uppercase;color:${look.accent};margin-bottom:${Math.round(look.kickerPx * 0.6)}px}.dot{width:7px;height:7px;border-radius:99px;background:${look.accent};box-shadow:0 0 10px ${look.accent}}.t{font-size:${look.titlePx}px;font-weight:600;line-height:1.25;letter-spacing:-0.01em}.b{margin-top:8px;font-size:${look.bodyPx}px;line-height:1.5;color:${look.cardMuted}}`
+  };
+}
+function calloutClip(shape, register, words, opts) {
+  const look = calloutLook(register, opts.scale ?? 1);
+  const box = calloutBox(shape, look, words);
+  const { html, css } = calloutSource(shape, look, words, box);
+  return {
+    id: opts.id,
+    kind: "html",
+    start: opts.start,
+    duration: opts.duration,
+    html,
+    css,
+    box,
+    transform: {
+      x: opts.at?.x ?? 0.5,
+      y: opts.at?.y ?? 0.5,
+      scale: 1,
+      rotation: 0
+    },
+    anim: { enter: "rise", exit: "fade" },
+    ...opts.pin ? { pin: opts.pin } : {}
+  };
+}
+function calloutGroundOf(css) {
+  const m = /background(?:-color)?\s*:\s*(#[0-9a-fA-F]{3,8}|rgba?\([^)]*\))/.exec(css);
+  if (!m) return null;
+  const rgb = parseCssColour(m[1]);
+  return rgb ? rgbToHex(rgb) : null;
+}
+function hexToRgb(hex) {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(hex.trim());
+  if (!m) return null;
+  let h = m[1];
+  if (h.length === 3)
+    h = h.split("").map((c) => c + c).join("");
+  return [
+    parseInt(h.slice(0, 2), 16),
+    parseInt(h.slice(2, 4), 16),
+    parseInt(h.slice(4, 6), 16)
+  ];
+}
+function rgbToHex([r, g, b]) {
+  const c = (v) => Math.round(clamp(v, 0, 255)).toString(16).padStart(2, "0");
+  return `#${c(r)}${c(g)}${c(b)}`;
+}
+function parseCssColour(s) {
+  const hex = hexToRgb(s);
+  if (hex) return hex;
+  const m = /rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/.exec(s);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function relativeLuminance([r, g, b]) {
+  const lin = (v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+function rgbToHsl([r, g, b]) {
+  const rr = r / 255;
+  const gg = g / 255;
+  const bb = b / 255;
+  const max = Math.max(rr, gg, bb);
+  const min = Math.min(rr, gg, bb);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h = 0;
+  if (max === rr) h = (gg - bb) / d + (gg < bb ? 6 : 0);
+  else if (max === gg) h = (bb - rr) / d + 2;
+  else h = (rr - gg) / d + 4;
+  return [h / 6, s, l];
+}
+function hslToHex(h, s, l) {
+  const f = (n) => {
+    const k = (n + h * 12) % 12;
+    const a = s * Math.min(l, 1 - l);
+    return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+  };
+  return rgbToHex([f(0) * 255, f(8) * 255, f(4) * 255]);
+}
+function deltaE(a, b) {
+  const la = rgbToLab(a);
+  const lb = rgbToLab(b);
+  return Math.hypot(la[0] - lb[0], la[1] - lb[1], la[2] - lb[2]);
+}
+function rgbToLab([r, g, b]) {
+  const lin = (v) => {
+    const c = v / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  const R = lin(r);
+  const G = lin(g);
+  const B = lin(b);
+  const x = (R * 0.4124 + G * 0.3576 + B * 0.1805) / 0.95047;
+  const y = R * 0.2126 + G * 0.7152 + B * 0.0722;
+  const z = (R * 0.0193 + G * 0.1192 + B * 0.9505) / 1.08883;
+  const f = (t) => t > 8856e-6 ? Math.cbrt(t) : 7.787 * t + 16 / 116;
+  return [116 * f(y) - 16, 500 * (f(x) - f(y)), 200 * (f(y) - f(z))];
+}
+function quoteFamily(family) {
+  const first = family.split(",")[0].trim().replace(/^['"]|['"]$/g, "");
+  const rest = family.includes(",") ? family.slice(family.indexOf(",") + 1).trim() : /mono/i.test(first) ? "ui-monospace,monospace" : "-apple-system,system-ui,sans-serif";
+  return /^[a-z-]+$/i.test(first) && /^(ui-|system-ui|sans-serif|serif|monospace)/.test(first) ? `${first},${rest}` : `'${first}',${rest}`;
+}
+function esc(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function clamp(v, lo, hi) {
+  return Math.max(lo, Math.min(hi, v));
+}
+
 // src/capture.ts
 var CHROME_TOP_MIN = 20;
 var CHROME_TOP_MAX = 220;
@@ -1102,7 +1306,7 @@ function sampleAt(points, t) {
   return { x: last.x, y: last.y };
 }
 function smoothCursor(track, options = {}) {
-  const factor = clamp(options.factor ?? 0.15, 0.01, 1);
+  const factor = clamp2(options.factor ?? 0.15, 0.01, 1);
   const fps = options.fps ?? 60;
   const raw = track.filter((e) => e.type === "move" || e.type === "down" || e.type === "up").map((e) => ({ t: e.t / 1e3, x: e.x, y: e.y }));
   if (raw.length === 0) return [];
@@ -1121,7 +1325,7 @@ function smoothCursor(track, options = {}) {
     if (clicks.length) {
       while (ci < clicks.length - 1 && t > clicks[ci].t + SNAP_AFTER) ci++;
       const ck = clicks[ci];
-      const u = clamp(
+      const u = clamp2(
         (t - (ck.t - SNAP_BEFORE)) / SNAP_BEFORE,
         0,
         t <= ck.t + SNAP_AFTER ? 1 : 0
@@ -1136,7 +1340,7 @@ function smoothCursor(track, options = {}) {
   }
   return out;
 }
-function clamp(v, lo, hi) {
+function clamp2(v, lo, hi) {
   return Math.max(lo, Math.min(hi, v));
 }
 
@@ -1782,7 +1986,7 @@ function focusFor(cluster, width, height, targetFill, minLevel, maxLevel) {
   const cx = clamp012(sx / n / width);
   const cy = clamp012(sy / n / height);
   const level = fitLevel({ x: 0, y: 0, w: maxW, h: maxH }, width, height, targetFill) ?? maxLevel;
-  return { cx, cy, level: clamp2(level, minLevel, maxLevel) };
+  return { cx, cy, level: clamp3(level, minLevel, maxLevel) };
 }
 function clusterFocus(events, width, height) {
   let sx = 0;
@@ -1815,11 +2019,11 @@ function clusterFocus(events, width, height) {
   } : null;
   return { cx: clamp012(sx / n / width), cy: clamp012(sy / n / height), rect };
 }
-function clamp2(v, lo, hi) {
+function clamp3(v, lo, hi) {
   return Math.max(lo, Math.min(hi, v));
 }
 function clamp012(v) {
-  return clamp2(v, 0, 1);
+  return clamp3(v, 0, 1);
 }
 function round(v) {
   return Math.round(v * 1e3) / 1e3;
@@ -7532,6 +7736,29 @@ function resolvePins(doc, layout, camera, zoomTrack) {
   }
   return out;
 }
+function pinCandidates(doc, clip) {
+  const rated = ratedSegments(doc);
+  const out = [];
+  const a0 = clip.start;
+  const a1 = clip.start + clip.duration;
+  for (const s of doc.source.meta.steps ?? []) {
+    if (s.skipped) continue;
+    const ref = pinReferent(doc, { step: s.id ?? s.step });
+    if (!ref) continue;
+    const ext = spanOutputExtent(rated, s.tStart, s.tEnd);
+    if (!ext) continue;
+    const overlap = Math.min(a1, ext.end) - Math.max(a0, ext.start);
+    if (overlap <= 0) continue;
+    out.push({
+      step: s.id ?? s.step,
+      do: s.do,
+      ...s.selector ? { selector: s.selector } : {},
+      output: { start: round7(ext.start), end: round7(ext.end) },
+      overlap: round7(overlap)
+    });
+  }
+  return out.sort((x, y) => y.overlap - x.overlap);
+}
 function overlayPinPoseAt(doc, o, t) {
   if (!o.pin) return null;
   const layout = docCardLayout(doc);
@@ -9079,24 +9306,31 @@ function destinationsForChannel(channel) {
 }
 
 // src/htmlStarters.ts
+function grammarStarter(id, name, words) {
+  const clip = calloutClip(id, HOUSE_REGISTER, words, {
+    id,
+    start: 0,
+    duration: 1,
+    scale: 1.4
+  });
+  return { id, name, html: clip.html, css: clip.css ?? "", box: clip.box };
+}
 var WORDS = "font-family:'Inter',-apple-system,system-ui,sans-serif;color:#fafafa;-webkit-font-smoothing:antialiased;";
 var MONO = "font-family:'JetBrains Mono',ui-monospace,monospace;";
 var CARD = "background:#0b0b0d;border:1px solid rgba(255,255,255,.08);border-radius:16px;box-shadow:0 24px 60px rgba(0,0,0,.45);";
 var HTML_STARTERS = [
-  {
-    id: "callout",
-    name: "Callout",
-    box: { width: 420, height: 132 },
-    html: '<div class="callout"><div class="head"><span class="dot"></span><span class="title">Title</span></div><div class="body">One line that says what this is.</div></div>',
-    css: `.callout{${WORDS}${CARD}box-sizing:border-box;width:420px;height:132px;padding:22px 24px}.head{display:flex;align-items:center;gap:10px}.dot{width:8px;height:8px;border-radius:99px;background:#4ade80;box-shadow:0 0 10px rgba(74,222,128,.9)}.title{font-size:20px;font-weight:600;letter-spacing:-0.01em}.body{margin-top:12px;font-size:15px;line-height:1.5;color:#8b8b94}`
-  },
-  {
-    id: "code",
-    name: "Code",
-    box: { width: 460, height: 168 },
-    html: '<div class="code"><span class="mut">// button.tsx</span>\n<span class="kw">export function</span> <span class="fn">Button</span>({ variant }) {\n  <span class="kw">return</span> <span class="tag">&lt;button</span> className={<span class="fn">cn</span>(variant)} <span class="tag">/&gt;</span>\n}</div>',
-    css: `.code{${MONO}${CARD}color:#e8e8ec;box-sizing:border-box;width:460px;height:168px;padding:22px 24px;font-size:14px;line-height:1.8;white-space:pre;letter-spacing:-0.01em}.kw{color:#c4b5fd}.fn{color:#7dd3fc}.tag{color:#f0abfc}.mut{color:#5b5b66}`
-  },
+  // The callout grammar (three shapes a viewer learns once), in the house
+  // register: a dark card in the house hue over a light app.
+  grammarStarter("note", "Note", {
+    kicker: "Presets",
+    title: "One of 43, picked here.",
+    body: "One line that says what this is about."
+  }),
+  grammarStarter("tag", "Tag", { kicker: "New in 2.0" }),
+  grammarStarter("code", "Code", {
+    kicker: "index.css",
+    code: ":root {\n  --primary: oklch(0.63 0.06 4.6);\n  --radius: 2.25rem;\n}"
+  }),
   {
     id: "terminal",
     name: "Terminal",
@@ -10637,6 +10871,9 @@ export {
   AUDIO_PLAN_STEP,
   BACKGROUND_Z,
   BASE_FRAME_STYLE,
+  CALLOUT_DEFAULT_BODY_PX,
+  CALLOUT_SHAPES,
+  CALLOUT_TYPE_RATIO,
   CAMERA_CENTRE_RAMP,
   CAMERA_COVER_MIN,
   CAMERA_FAR,
@@ -10711,6 +10948,7 @@ export {
   FREEZE_SECONDS_MAX,
   FREEZE_SECONDS_MIN,
   HOUSE_GRADIENT,
+  HOUSE_REGISTER,
   HTML_LAYER_FOREIGN_FIELDS,
   HTML_LAYER_MAX_BYTES,
   HTML_LAYER_SVG_CODE,
@@ -10802,6 +11040,11 @@ export {
   audioLane,
   backdropMedia,
   buildDigest,
+  calloutBox,
+  calloutClip,
+  calloutGroundOf,
+  calloutLook,
+  calloutSource,
   camBubbleRect,
   camBubbleRectAt,
   camLane,
@@ -10836,6 +11079,7 @@ export {
   cssFamilies,
   cssWeights,
   cursorIdleFade,
+  deltaE,
   deriveViewportCrop,
   destinationById,
   destinationsForChannel,
@@ -10873,6 +11117,7 @@ export {
   frameGeometry,
   freezeLane,
   freezeOutputExtents,
+  hexToRgb,
   hexToRgbTriplet,
   houseLook,
   htmlLayerBleed,
@@ -10943,9 +11188,11 @@ export {
   overlaysLane,
   ownFreezes,
   pageDisplayUrl,
+  parseCssColour,
   parsePoseId,
   pickStyle,
   pinBox,
+  pinCandidates,
   pinPlacement,
   pinRectOnScreen,
   pinReferent,
@@ -10963,6 +11210,7 @@ export {
   recommendedExportResolution,
   refillAudioBeds,
   rejectSpan,
+  relativeLuminance,
   removeSourceRange,
   removeSpeedInRange,
   resolveExportSize,
@@ -10973,6 +11221,7 @@ export {
   resolveZoomStyle,
   restLeanOf,
   restSpansThroughTransitions,
+  rgbToHex,
   sameMedia,
   sceneChanges,
   scrollRuns,