@flaier/core 0.1.1 → 0.1.7

package/README.md

@@ -1,18 +1,51 @@
-# @flaier/core
+# @flaier/core ✨
 
 [![npm version](https://img.shields.io/npm/v/%40flaier%2Fcore?style=flat-square)](https://www.npmjs.com/package/@flaier/core)
 [![npm downloads](https://img.shields.io/npm/dm/%40flaier%2Fcore?style=flat-square)](https://www.npmjs.com/package/@flaier/core)
 [![License](https://img.shields.io/github/license/WeAreRetex/flaier?style=flat-square)](https://github.com/WeAreRetex/flaier/blob/main/LICENSE)
 
-Vue components, catalog helpers, and styles for rendering Flaier flow specs in narrative and architecture modes.
+**The Vue renderer for explainable flows and architecture walkthroughs.**
 
-## Install
+`@flaier/core` is the main Vue renderer for Flaier.
+
+Use it when you want to turn a JSON flow spec or manifest into an interactive walkthrough inside a Vue application, a demo surface, or an internal developer tool.
+
+## 🎯 What It Is Used For
+
+- Explaining how a request, workflow, or architecture behaves step by step.
+- Embedding interactive system diagrams in Vue apps instead of static screenshots.
+- Rendering AI-generated flow artifacts in a polished UI people can actually inspect.
+- Exporting diagrams for docs, decks, tickets, and async review threads.
+
+## 🌟 Features
+
+- 🎬 Narrative playback with active-step focus, autoplay, and timeline controls.
+- 🏗 Architecture rendering with zones, inspector panels, and topology-first layouts.
+- 🗂 Manifest support for loading many related flows behind one entry point.
+- 📤 PNG and PDF export for the full diagram, not just the visible viewport.
+- 🎨 Bundled CSS and built-in node renderers so the default experience looks production-ready fast.
+
+## 🧭 Common Use Cases
+
+**Vue Apps**
+
+Embed flows directly inside internal tools, product surfaces, or engineering portals without building a renderer from scratch.
+
+**AI-Generated Specs**
+
+Point the component at checked-in JSON, generated artifacts, or remote spec URLs and render them in a UI people can step through.
+
+**Architecture Reviews**
+
+Switch to architecture mode when you need a cleaner system view for discussing boundaries, dependencies, and transitions.
+
+## 📦 Install
 
 ```bash
 npm i @flaier/core
 ```
 
-## Usage
+## 🚀 Basic Usage
 
 ```vue
 <script setup lang="ts">
@@ -25,14 +58,28 @@ import "@flaier/core/style.css";
 </template>
 ```
 
-## Features
+## 🧠 Accepted Inputs
+
+`Flaier` accepts:
+
+- a single flow spec object,
+- a single flow spec JSON path or URL,
+- a multi-flow manifest object,
+- or a multi-flow manifest JSON path or URL.
+
+That makes `@flaier/core` a good fit whether your specs come from checked-in files, generated artifacts, or remote APIs.
+
+## 🧩 When To Use `@flaier/nuxt` Instead
+
+Stay with `@flaier/core` when you are in plain Vue.
+
+Reach for [`@flaier/nuxt`](https://www.npmjs.com/package/@flaier/nuxt) when you want:
 
-- Narrative playback with active-step focus, autoplay, and timeline controls.
-- Architecture rendering with zones, inspector panels, and export controls.
-- Manifest support for loading many related flows behind one entry point.
-- PNG and PDF export for the full diagram, not just the visible viewport.
+- global Nuxt wrapper components,
+- easy embedding in Nuxt Content or Docus markdown,
+- or docs-site-friendly fullscreen and client-only behavior out of the box.
 
-## Links
+## 🔗 Links
 
 - Repository: https://github.com/WeAreRetex/flaier
 - Package source: https://github.com/WeAreRetex/flaier/tree/main/packages/core

package/dist/context.d.ts

@@ -6,6 +6,7 @@ export interface FlaierRuntimeContext {
     nodes: Ref<FlaierCustomNodeDefinitions>;
     flowOptions: Ref<FlaierFlowOption[]>;
     activeFlowId: Ref<string | null>;
+    viewportResetToken: Ref<number>;
     setActiveFlow: (flowId: string) => void;
 }
 export declare const flaierRuntimeKey: InjectionKey<FlaierRuntimeContext>;

package/dist/index.js

@@ -2406,6 +2406,10 @@ const DEFAULT_DAGRE_NODE_SEP_VERTICAL = 120;
 const DEFAULT_DAGRE_EDGE_SEP = 30;
 const OVERVIEW_ENTER_ZOOM = .52;
 const OVERVIEW_EXIT_ZOOM = .62;
+const NARRATIVE_FOCUS_HORIZONTAL_CONTEXT = 420;
+const NARRATIVE_FOCUS_VERTICAL_CONTEXT = 320;
+const NARRATIVE_FOCUS_MIN_ZOOM = .58;
+const NARRATIVE_FOCUS_MAX_ZOOM = 1.35;
 const FLAIER_THEME_STORAGE_KEY = "flaier-ui-theme";
 const ARCHITECTURE_ZONE_MIN_CONTENT_PADDING = 44;
 const ARCHITECTURE_ZONE_MIN_BOTTOM_PADDING = 88;
@@ -3627,8 +3631,12 @@ var FlowTimelineRenderer_default = /* @__PURE__ */ defineComponent({
 				timer = null;
 			}
 		}
-		function next() {
+		function pauseNarrativePlayback() {
+			if (!isArchitectureMode.value) playing.value = false;
+		}
+		function next(manual = true) {
 			if (isArchitectureMode.value) return false;
+			if (manual) pauseNarrativePlayback();
 			if (currentStep.value >= totalSteps.value - 1) return false;
 			currentStep.value += 1;
 			return true;
@@ -3641,15 +3649,17 @@ var FlowTimelineRenderer_default = /* @__PURE__ */ defineComponent({
 			clearTimer();
 			if (!isPlaying || steps <= 1) return;
 			timer = setInterval(() => {
-				if (!next()) playing.value = false;
+				if (!next(false)) playing.value = false;
 			}, interval);
 		}, { immediate: true });
-		function prev() {
+		function prev(manual = true) {
 			if (isArchitectureMode.value) return;
+			if (manual) pauseNarrativePlayback();
 			if (currentStep.value > 0) currentStep.value -= 1;
 		}
-		function goTo(step) {
+		function goTo(step, manual = true) {
 			if (isArchitectureMode.value) return;
+			if (manual) pauseNarrativePlayback();
 			currentStep.value = clampStep(step);
 		}
 		function togglePlay() {
@@ -4364,6 +4374,7 @@ var FlowTimelineRenderer_default = /* @__PURE__ */ defineComponent({
 		function chooseChoice(choiceId) {
 			const node = activeNode.value;
 			if (!node) return;
+			pauseNarrativePlayback();
 			if (!(outgoingNodeKeys.value[node.key] ?? []).includes(choiceId)) return;
 			selectedBranchByNode.value = {
 				...selectedBranchByNode.value,
@@ -4474,6 +4485,33 @@ var FlowTimelineRenderer_default = /* @__PURE__ */ defineComponent({
 			containerHeight.value = element?.clientHeight ?? 0;
 			containerReady.value = containerWidth.value > 0 && containerHeight.value > 0;
 		}
+		function waitForAnimationFrame() {
+			return new Promise((resolve) => {
+				if (typeof window === "undefined" || typeof window.requestAnimationFrame !== "function") {
+					setTimeout(resolve, 16);
+					return;
+				}
+				window.requestAnimationFrame(() => {
+					resolve();
+				});
+			});
+		}
+		async function waitForViewportLayoutStability() {
+			await nextTick();
+			await waitForAnimationFrame();
+			await waitForAnimationFrame();
+			updateContainerReady();
+			await nextTick();
+		}
+		function getNarrativeFocusZoom(size) {
+			const width = Math.max(1, containerWidth.value);
+			const height = Math.max(1, containerHeight.value);
+			const focusWidth = Math.max(size.width * 1.35, size.width + NARRATIVE_FOCUS_HORIZONTAL_CONTEXT);
+			const focusHeight = Math.max(size.height * 1.45, size.height + NARRATIVE_FOCUS_VERTICAL_CONTEXT);
+			const zoom = Math.min(width / focusWidth, height / focusHeight);
+			if (!Number.isFinite(zoom)) return 1;
+			return Math.max(NARRATIVE_FOCUS_MIN_ZOOM, Math.min(NARRATIVE_FOCUS_MAX_ZOOM, zoom));
+		}
 		const sceneStyle = computed(() => ({ height: `${Math.max(containerHeight.value, containerMinHeight.value)}px` }));
 		onMounted(() => {
 			if (typeof document !== "undefined") {
@@ -4496,6 +4534,33 @@ var FlowTimelineRenderer_default = /* @__PURE__ */ defineComponent({
 		const canExportDiagram = computed(() => {
 			return Boolean(viewportReady.value && diagramBounds.value);
 		});
+		async function refitViewportAfterContainerChange() {
+			if (!nodes.value.length) return;
+			await waitForViewportLayoutStability();
+			if (!viewportReady.value || nodes.value.length === 0) return;
+			if (isArchitectureMode.value || overviewMode.value) {
+				await Promise.resolve(fitView({
+					duration: isArchitectureMode.value ? 260 : 280,
+					padding: isArchitectureMode.value ? .18 : .3,
+					maxZoom: isArchitectureMode.value ? 1.15 : .95
+				}));
+				return;
+			}
+			const target = narrativeFocusTarget.value;
+			if (!target) {
+				await Promise.resolve(fitView({
+					duration: 280,
+					padding: .3,
+					maxZoom: .95
+				}));
+				return;
+			}
+			await nextTick();
+			await Promise.resolve(setCenter(target.x, target.y, {
+				duration: 280,
+				zoom: target.zoom
+			}));
+		}
 		watch(canExportDiagram, (canExport) => {
 			if (!canExport) closeExportMenu();
 		});
@@ -4511,6 +4576,7 @@ var FlowTimelineRenderer_default = /* @__PURE__ */ defineComponent({
 			};
 			return {
 				signature: [
+					currentStep.value,
 					node.id,
 					Math.round(node.position.x),
 					Math.round(node.position.y),
@@ -4520,10 +4586,12 @@ var FlowTimelineRenderer_default = /* @__PURE__ */ defineComponent({
 					Math.round(containerHeight.value)
 				].join(":"),
 				x: node.position.x + size.width / 2,
-				y: node.position.y + size.height / 2
+				y: node.position.y + size.height / 2,
+				zoom: getNarrativeFocusZoom(size)
 			};
 		});
 		const narrativeFitSignature = ref("");
+		const suppressNarrativeResizeFit = ref(false);
 		watch([
 			viewportReady,
 			isArchitectureMode,
@@ -4534,6 +4602,10 @@ var FlowTimelineRenderer_default = /* @__PURE__ */ defineComponent({
 			if (!ready || architectureMode || currentNodes.length === 0) return;
 			const signature = [`${Math.round(width)}x${Math.round(height)}`, ...currentNodes.map((node) => `${node.id}:${Math.round(node.position.x)}:${Math.round(node.position.y)}`)].join("|");
 			if (signature === narrativeFitSignature.value) return;
+			if (suppressNarrativeResizeFit.value && narrativeFocusTarget.value) {
+				narrativeFitSignature.value = signature;
+				return;
+			}
 			narrativeFitSignature.value = signature;
 			nextTick(() => {
 				fitView({
@@ -4546,15 +4618,15 @@ var FlowTimelineRenderer_default = /* @__PURE__ */ defineComponent({
 		watch(() => narrativeFocusTarget.value?.signature ?? "", () => {
 			const target = narrativeFocusTarget.value;
 			if (!target) return;
-			const zoom = Number.isFinite(viewport.value.zoom) ? viewport.value.zoom : 1;
 			nextTick(() => {
 				setCenter(target.x, target.y, {
 					duration: 280,
-					zoom
+					zoom: target.zoom
 				});
 			});
 		}, { immediate: true });
 		const architectureFitSignature = ref("");
+		const lastViewportResetToken = ref(0);
 		watch([
 			viewportReady,
 			isArchitectureMode,
@@ -4574,6 +4646,25 @@ var FlowTimelineRenderer_default = /* @__PURE__ */ defineComponent({
 				});
 			});
 		}, { immediate: true });
+		watch([() => runtime.viewportResetToken.value, viewportReady], ([token, ready]) => {
+			if (!ready || token <= lastViewportResetToken.value) return;
+			lastViewportResetToken.value = token;
+			narrativeFitSignature.value = "";
+			architectureFitSignature.value = "";
+			const shouldSuppressNarrativeFit = Boolean(narrativeFocusTarget.value);
+			if (shouldSuppressNarrativeFit) suppressNarrativeResizeFit.value = true;
+			(async () => {
+				try {
+					await refitViewportAfterContainerChange();
+				} finally {
+					if (shouldSuppressNarrativeFit) {
+						await waitForAnimationFrame();
+						await waitForAnimationFrame();
+						suppressNarrativeResizeFit.value = false;
+					}
+				}
+			})();
+		}, { immediate: true });
 		watch(isArchitectureMode, (architectureMode) => {
 			if (architectureMode) {
 				playing.value = false;
@@ -5106,6 +5197,10 @@ var Flaier_default = /* @__PURE__ */ defineComponent({
 		nodes: {
 			type: Object,
 			required: false
+		},
+		viewportResetToken: {
+			type: Number,
+			required: false
 		}
 	},
 	emits: [
@@ -5126,6 +5221,9 @@ var Flaier_default = /* @__PURE__ */ defineComponent({
 		let sourceRequestId = 0;
 		let flowRequestId = 0;
 		const customNodes = computed(() => normalizeFlaierCustomNodes(props.nodes));
+		const viewportResetToken = computed(() => {
+			return typeof props.viewportResetToken === "number" && Number.isFinite(props.viewportResetToken) ? Math.max(0, Math.floor(props.viewportResetToken)) : 0;
+		});
 		const rendererRegistry = computed(() => createFlaierRendererRegistry({ nodes: customNodes.value }));
 		provide(flaierRuntimeKey, {
 			spec: resolvedSpec,
@@ -5133,6 +5231,7 @@ var Flaier_default = /* @__PURE__ */ defineComponent({
 			nodes: customNodes,
 			flowOptions,
 			activeFlowId,
+			viewportResetToken,
 			setActiveFlow
 		});
 		watch([() => props.src, () => props.themeMode], () => {
@@ -5556,12 +5655,17 @@ var FlaierPanel_default = /* @__PURE__ */ _plugin_vue_export_helper_default(/* @
 		nodes: {
 			type: Object,
 			required: false
+		},
+		viewportResetToken: {
+			type: Number,
+			required: false
 		}
 	},
 	setup(__props) {
 		const props = __props;
 		const { fullscreen, closeFullscreen, toggleFullscreen } = useFlaierFullscreen();
 		const fullscreenActive = computed(() => props.fullscreenEnabled && fullscreen.value);
+		const viewportResetToken = ref(0);
 		const containerStyle = computed(() => {
 			const minHeight = Number.isFinite(props.minHeight) ? Math.max(280, Math.floor(props.minHeight)) : 420;
 			return {
@@ -5573,6 +5677,9 @@ var FlaierPanel_default = /* @__PURE__ */ _plugin_vue_export_helper_default(/* @
 		watch(() => props.fullscreenEnabled, (enabled) => {
 			if (!enabled && fullscreen.value) closeFullscreen();
 		});
+		watch(fullscreenActive, () => {
+			viewportResetToken.value += 1;
+		}, { flush: "post" });
 		return (_ctx, _cache) => {
 			return openBlock(), createBlock(Teleport, {
 				to: "body",
@@ -5592,13 +5699,15 @@ var FlaierPanel_default = /* @__PURE__ */ _plugin_vue_export_helper_default(/* @
 				"auto-play": __props.autoPlay,
 				interval: __props.interval,
 				"theme-mode": __props.themeMode,
-				nodes: __props.nodes
+				nodes: __props.nodes,
+				"viewport-reset-token": viewportResetToken.value
 			}, null, 8, [
 				"src",
 				"auto-play",
 				"interval",
 				"theme-mode",
-				"nodes"
+				"nodes",
+				"viewport-reset-token"
 			]), __props.fullscreenEnabled ? (openBlock(), createElementBlock("button", {
 				key: 0,
 				type: "button",