@ssgoi/qwik 6.6.4

package/README.md

@@ -0,0 +1,84 @@
+# @ssgoi/qwik
+
+Qwik bindings for SSGOI - native app-like page transitions for Qwik and Qwik City.
+
+Full setup reference for AI agents:
+
+https://ssgoi.dev/llms.txt
+
+## Install
+
+```bash
+npm install @ssgoi/qwik
+```
+
+## Qwik City
+
+Qwik serializes component state for resumability, while SSGOI transition configs contain functions. Pass the config as a QRL factory (`config$`) so the adapter can resolve it in the browser before starting the DOM observer.
+
+Use `useSsgoi(ref, { config$ })` directly in the Qwik City layout that owns the route `<Slot />`:
+
+```tsx
+import { $, Slot, component$, useSignal } from "@builder.io/qwik";
+import { Link, useLocation } from "@builder.io/qwik-city";
+import { useSsgoi } from "@ssgoi/qwik";
+import { drill, zoom } from "@ssgoi/qwik/view-transitions";
+
+const ssgoiConfig$ = $(() => ({
+  preserveScroll: { exclude: ["/posts/*"] },
+  transitions: [
+    zoom({ paths: ["/gallery", "/gallery/*"], type: "expand" }),
+    drill({ enter: "/posts/*", exit: "/posts" }),
+  ],
+}));
+
+export default component$(() => {
+  const location = useLocation();
+  const ssgoiRoot = useSignal<HTMLElement>();
+
+  useSsgoi(ssgoiRoot, { config$: ssgoiConfig$ });
+
+  return (
+    <main
+      ref={ssgoiRoot}
+      class="relative z-0 h-dvh overflow-y-auto overflow-x-clip"
+    >
+      <Slot />
+      <Link href="/posts/">Posts</Link>
+      <p>{location.url.pathname}</p>
+    </main>
+  );
+});
+```
+
+Set `data-ssgoi-transition` directly on each routed page boundary. The value only needs to match the `paths`, `from`, or `to` values in your config:
+
+```tsx
+export default component$(() => {
+  return (
+    <section data-ssgoi-transition="/posts" class="min-h-full">
+      Posts
+    </section>
+  );
+});
+```
+
+Import view-level factories from `@ssgoi/qwik/view-transitions`.
+
+## Qwik City Notes
+
+- Declare configs with Qwik `$`, for example `const config$ = $(() => ({ transitions: [...] }))`. Do not pass a plain config object through component props.
+- Keep the route `<Slot />` inside the same layout element observed by `useSsgoi`.
+- Mark pages directly with `data-ssgoi-transition`; do not put one generic boundary around the parent `<Slot />`.
+- Put layout-shell classes such as `relative z-0 overflow-x-clip` on the SSGOI root/scroll container, not on every page marker.
+
+`Ssgoi` is also exported for wrapping concrete children outside Qwik City routing. In Qwik City layouts, prefer `useSsgoi` because forwarding a route `<Slot />` through another component can prevent routed content from being projected into the live DOM during navigation.
+
+## Troubleshooting
+
+If route navigation works but no transition runs:
+
+1. Confirm the layout calls `useSsgoi(ssgoiRoot, { config$ })`.
+2. Confirm `config$` is created with Qwik `$`.
+3. Confirm the SSGOI root contains the route `<Slot />` directly.
+4. Confirm every routed page has a `data-ssgoi-transition` value that matches your transition config.

package/lib/index.qwik.cjs

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const types = require("@ssgoi/core/types");
+const useSsgoi = require("./use-ssgoi.qwik.cjs");
+const ssgoi = require("./ssgoi.qwik.cjs");
+const ssgoiTransition = require("./ssgoi-transition.qwik.cjs");
+const core = require("@ssgoi/core");
+exports.useSsgoi = useSsgoi.useSsgoi;
+exports.Ssgoi = ssgoi.Ssgoi;
+exports.SsgoiTransition = ssgoiTransition.SsgoiTransition;
+Object.keys(types).forEach((k) => {
+  if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: () => types[k]
+  });
+});
+Object.keys(core).forEach((k) => {
+  if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: () => core[k]
+  });
+});

package/lib/index.qwik.mjs

@@ -0,0 +1,10 @@
+export * from "@ssgoi/core/types";
+import { useSsgoi } from "./use-ssgoi.qwik.mjs";
+import { Ssgoi } from "./ssgoi.qwik.mjs";
+import { SsgoiTransition } from "./ssgoi-transition.qwik.mjs";
+export * from "@ssgoi/core";
+export {
+  Ssgoi,
+  SsgoiTransition,
+  useSsgoi
+};

package/lib/ssgoi-transition.qwik.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("@builder.io/qwik/jsx-runtime");
+const qwik = require("@builder.io/qwik");
+const SsgoiTransition = qwik.component$(({ id, class: className }) => {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", {
+    "data-ssgoi-transition": id,
+    class: className,
+    children: /* @__PURE__ */ jsxRuntime.jsx(qwik.Slot, {})
+  });
+});
+exports.SsgoiTransition = SsgoiTransition;

package/lib/ssgoi-transition.qwik.mjs

@@ -0,0 +1,12 @@
+import { jsx } from "@builder.io/qwik/jsx-runtime";
+import { component$, Slot } from "@builder.io/qwik";
+const SsgoiTransition = component$(({ id, class: className }) => {
+  return /* @__PURE__ */ jsx("div", {
+    "data-ssgoi-transition": id,
+    class: className,
+    children: /* @__PURE__ */ jsx(Slot, {})
+  });
+});
+export {
+  SsgoiTransition
+};

package/lib/ssgoi.qwik.cjs

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("@builder.io/qwik/jsx-runtime");
+const qwik = require("@builder.io/qwik");
+const useSsgoi = require("./use-ssgoi.qwik.cjs");
+const Ssgoi = qwik.component$(({ config$, host$ }) => {
+  const root = qwik.useSignal();
+  useSsgoi.useSsgoi(root, {
+    config$,
+    host$
+  });
+  return /* @__PURE__ */ jsxRuntime.jsx("div", {
+    ref: root,
+    "data-ssgoi-root": "",
+    style: {
+      display: "contents"
+    },
+    children: /* @__PURE__ */ jsxRuntime.jsx(qwik.Slot, {})
+  });
+});
+exports.Ssgoi = Ssgoi;

package/lib/ssgoi.qwik.mjs

@@ -0,0 +1,21 @@
+import { jsx } from "@builder.io/qwik/jsx-runtime";
+import { component$, useSignal, Slot } from "@builder.io/qwik";
+import { useSsgoi } from "./use-ssgoi.qwik.mjs";
+const Ssgoi = component$(({ config$, host$ }) => {
+  const root = useSignal();
+  useSsgoi(root, {
+    config$,
+    host$
+  });
+  return /* @__PURE__ */ jsx("div", {
+    ref: root,
+    "data-ssgoi-root": "",
+    style: {
+      display: "contents"
+    },
+    children: /* @__PURE__ */ jsx(Slot, {})
+  });
+});
+export {
+  Ssgoi
+};

package/lib/types.qwik.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const types = require("@ssgoi/core/types");
+Object.keys(types).forEach((k) => {
+  if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: () => types[k]
+  });
+});

package/lib/types.qwik.mjs

@@ -0,0 +1 @@
+export * from "@ssgoi/core/types";

package/lib/use-ssgoi.qwik.cjs

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const qwik = require("@builder.io/qwik");
+const internal = require("@ssgoi/core/internal");
+const useSsgoi = (root, options = {}) => {
+  const configQrl = options.config$;
+  const hostQrl = options.host$;
+  qwik.useVisibleTask$(async ({ cleanup, track }) => {
+    const element = track(() => root.value);
+    if (!element) return;
+    const configFactory = configQrl ? await configQrl.resolve() : void 0;
+    const hostFactory = hostQrl ? await hostQrl.resolve() : void 0;
+    const config = configFactory ? await configFactory() : {};
+    const host = hostFactory ? await hostFactory() : void 0;
+    const ssgoi = internal.createSggoiTransitionContext(config, {
+      host
+    });
+    const stopObserving = internal.observeSsgoiTransitions(element, ssgoi);
+    cleanup(stopObserving);
+  }, {
+    strategy: "document-ready"
+  });
+};
+exports.useSsgoi = useSsgoi;

package/lib/use-ssgoi.qwik.mjs

@@ -0,0 +1,24 @@
+import { useVisibleTask$ } from "@builder.io/qwik";
+import { createSggoiTransitionContext, observeSsgoiTransitions } from "@ssgoi/core/internal";
+const useSsgoi = (root, options = {}) => {
+  const configQrl = options.config$;
+  const hostQrl = options.host$;
+  useVisibleTask$(async ({ cleanup, track }) => {
+    const element = track(() => root.value);
+    if (!element) return;
+    const configFactory = configQrl ? await configQrl.resolve() : void 0;
+    const hostFactory = hostQrl ? await hostQrl.resolve() : void 0;
+    const config = configFactory ? await configFactory() : {};
+    const host = hostFactory ? await hostFactory() : void 0;
+    const ssgoi = createSggoiTransitionContext(config, {
+      host
+    });
+    const stopObserving = observeSsgoiTransitions(element, ssgoi);
+    cleanup(stopObserving);
+  }, {
+    strategy: "document-ready"
+  });
+};
+export {
+  useSsgoi
+};

package/lib/view-transitions.qwik.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const core = require("@ssgoi/core");
+Object.keys(core).forEach((k) => {
+  if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: () => core[k]
+  });
+});

package/lib/view-transitions.qwik.mjs

@@ -0,0 +1 @@
+export * from "@ssgoi/core";

package/lib-types/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export { useSsgoi, type UseSsgoiOptions } from "./use-ssgoi";
+export { Ssgoi } from "./ssgoi";
+export { SsgoiTransition } from "./ssgoi-transition";
+export * from "@ssgoi/core";

package/lib-types/ssgoi-transition.d.ts

@@ -0,0 +1,11 @@
+export interface SsgoiTransitionProps {
+  id: string;
+  class?: string;
+}
+/**
+ * Marks a subtree as a Ssgoi page boundary.
+ *
+ * @deprecated Set `data-ssgoi-transition` directly on the page boundary
+ * element inside `<Ssgoi>` instead.
+ */
+export declare const SsgoiTransition: import("@builder.io/qwik").Component<SsgoiTransitionProps>;

package/lib-types/ssgoi.d.ts

@@ -0,0 +1,6 @@
+import type { SsgoiConfigQrl, SsgoiHostQrl } from "./types";
+export interface SsgoiProps {
+    config$?: SsgoiConfigQrl;
+    host$?: SsgoiHostQrl;
+}
+export declare const Ssgoi: import("@builder.io/qwik").Component<SsgoiProps>;

package/lib-types/types.d.ts

@@ -0,0 +1,11 @@
+import type { QRL } from "@builder.io/qwik";
+import type { HostAnimation } from "@ssgoi/core/internal";
+import type { SsgoiConfig } from "@ssgoi/core/types";
+export * from "@ssgoi/core/types";
+export type SsgoiConfigFactory = () => SsgoiConfig | Promise<SsgoiConfig>;
+export type SsgoiHostFactory = () =>
+  | HostAnimation
+  | undefined
+  | Promise<HostAnimation | undefined>;
+export type SsgoiConfigQrl = QRL<SsgoiConfigFactory>;
+export type SsgoiHostQrl = QRL<SsgoiHostFactory>;

package/lib-types/use-ssgoi.d.ts

@@ -0,0 +1,7 @@
+import { type Signal } from "@builder.io/qwik";
+import type { SsgoiConfigQrl, SsgoiHostQrl } from "./types";
+export interface UseSsgoiOptions {
+    config$?: SsgoiConfigQrl;
+    host$?: SsgoiHostQrl;
+}
+export declare const useSsgoi: (root: Signal<HTMLElement | undefined>, options?: UseSsgoiOptions) => void;

package/lib-types/view-transitions.d.ts

@@ -0,0 +1 @@
+export * from "@ssgoi/core";

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@ssgoi/qwik",
+  "version": "6.6.4",
+  "description": "Qwik bindings for SSGOI - Native app-like page transitions for Qwik and Qwik City applications",
+  "private": false,
+  "sideEffects": false,
+  "type": "module",
+  "main": "./lib/index.qwik.mjs",
+  "qwik": "./lib/index.qwik.mjs",
+  "types": "./lib-types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib-types/index.d.ts",
+      "import": "./lib/index.qwik.mjs",
+      "require": "./lib/index.qwik.cjs"
+    },
+    "./types": {
+      "types": "./lib-types/types.d.ts",
+      "import": "./lib/types.qwik.mjs",
+      "require": "./lib/types.qwik.cjs"
+    },
+    "./view-transitions": {
+      "types": "./lib-types/view-transitions.d.ts",
+      "import": "./lib/view-transitions.qwik.mjs",
+      "require": "./lib/view-transitions.qwik.cjs"
+    }
+  },
+  "files": [
+    "lib",
+    "lib-types"
+  ],
+  "dependencies": {
+    "@ssgoi/core": "^6.6.4"
+  },
+  "peerDependencies": {
+    "@builder.io/qwik": "^1.20.0"
+  },
+  "devDependencies": {
+    "@builder.io/qwik": "^1.20.0",
+    "@eslint/js": "^9.30.1",
+    "@types/node": "^22.10.6",
+    "eslint": "^9.30.1",
+    "eslint-plugin-qwik": "^1.20.0",
+    "globals": "^16.3.0",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.35.1",
+    "vite": "^7.0.4",
+    "vite-tsconfig-paths": "^5.1.4"
+  },
+  "keywords": [
+    "qwik",
+    "qwik-city",
+    "page-transition",
+    "page-transitions",
+    "view-transitions",
+    "view-transition-api-alternative",
+    "animation",
+    "ssgoi",
+    "spring-physics",
+    "cross-browser",
+    "navigation-animation",
+    "hero-transition",
+    "shared-element-transition"
+  ],
+  "author": "MeurSyphus <tmdeoans@snu.ac.kr>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meursyphus/ssgoi.git",
+    "directory": "packages/qwik"
+  },
+  "homepage": "https://ssgoi.dev",
+  "bugs": {
+    "url": "https://github.com/meursyphus/ssgoi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "pnpm run build.lib && pnpm run build.types",
+    "build.lib": "vite build --mode lib",
+    "build.types": "tsc --emitDeclarationOnly",
+    "dev": "vite build --watch --mode lib",
+    "watch": "vite build --watch --mode lib",
+    "lint": "eslint \"src/**/*.ts*\""
+  }
+}