@slopmachine/svelte 0.1.10 → 0.1.13

package/Agents.md

@@ -0,0 +1,45 @@
+# Svelte SDK Coding Conventions
+
+This document outlines the coding conventions, architecture, and patterns used in the `@slopmachine/svelte` SDK package. Future agents and contributors should adhere to these guidelines when making changes.
+
+## 1. Svelte 5 Runes
+
+The SDK utilizes **Svelte 5** and exclusively relies on **runes** for state management and reactivity.
+
+- `$props()`: Used for defining component properties. Ensure default values are handled here, and `...restProps` is utilized to spread unused properties onto underlying DOM elements (e.g., `<img>`).
+- `$state()`: Used for localized component state (e.g., loading states, URLs).
+- `$derived()`: Used for computed values that depend on state or props (e.g., computing an image URL based on options).
+- `$effect()`: Used for side effects, such as tracking prop changes over time, fetching, or debouncing.
+
+## 2. TypeScript and Typing
+
+- All Svelte components must use `<script lang="ts">`.
+- Props should be strictly typed. Interfaces should extend the base option types provided by the core package. For example, `SlopImageProps` extends `SlopImageOptions` from `@slopmachine/core`.
+- Custom markup passed as props (e.g., a custom loader) should utilize the Svelte 5 `Snippet` type imported from `svelte`.
+
+## 3. Dependency Management
+
+- **Core SDK Logic**: Do not duplicate core logic (like URL generation). Always import utility functions and base types from the `@slopmachine/core` package.
+- **Peer Dependencies**: The Svelte package lists `svelte` (version `^5.0.0`) as a peer dependency.
+
+## 4. Component Structure
+
+Components should follow a clear top-to-bottom structure:
+
+1.  **Block Comments**: A descriptive JSDoc/HTML block comment at the top of the file outlining the `@component`, its description, `@example`, and `@version`.
+2.  **Script Tag**: `<script lang="ts">` containing imports, type definitions, runes (`$props`, `$state`, etc.), and local functions.
+3.  **Markup**: The Svelte HTML template using Svelte 5 logic blocks (`{#if}`, `{@render snippet()}`).
+4.  **Styles**: A `<style>` tag scoped to the component. Use CSS variables with sensible fallbacks (e.g., `var(--muted, #f3f4f6)`) to allow consumer theming while maintaining a good default appearance.
+
+## 5. Exporting Patterns
+
+- **No Bundling**: The package is published as uncompiled source code to let the consuming project's bundler handle the Svelte compilation.
+- **package.json Setup**:
+  - Exposes `"type": "module"`.
+  - The `"svelte"`, `"main"`, and `"exports"` fields point directly to `./src/index.ts`.
+- Component exports should be simple and direct via `src/index.ts`.
+
+## 6. Error Handling and Loading
+
+- Implement clean fallbacks for failing resources (like broken image links). The `SlopImage` component demonstrates using `fetch` to proactively capture error statuses, falling back to an error state or logging.
+- Support default loading indicators (spinners/shimmer effects) alongside customizable slots/snippets (e.g., `loader`) for a better user experience.

package/README.md

@@ -14,13 +14,13 @@ pnpm add @slopmachine/svelte
 
 ## Demo
 
-https://slopmachine-dev.github.io/slopmachine-sdk/svelte/
+https://slopmachine-dev.github.io/slopmachine-sdk/demo-svelte/
 
 ## Usage
 
 ```svelte
 <script lang="ts">
-  import { SlopImage } from '@slopmachine/svelte';
+  import { SlopImage } from "@slopmachine/svelte";
 </script>
 
 <div style="width: 400px; height: 400px;">

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@slopmachine/svelte",
-  "version": "0.1.10",
-  "description": "Svelte wrapper for SlopMachine",
+  "version": "0.1.13",
+  "description": "The official Svelte SDK for Slop Machine",
   "type": "module",
   "main": "src/index.ts",
   "svelte": "src/index.ts",

package/src/SlopImage.svelte

@@ -1,9 +1,46 @@
+<!--
+  @component
+  Renders an image generated by Slop Machine.
+
+  This component automatically constructs the correct URL for the Slop Machine API,
+  displays a loading skeleton or custom loader while fetching, and handles errors.
+
+  @example
+  ```svelte
+  <SlopImage
+    bucketId="my-bucket"
+    resultId="some-result"
+    aspectRatio="16:9"
+    class="rounded-lg"
+  />
+  ```
+
+  @version 0.1.13
+-->
 <script lang="ts">
-  import { buildImageUrl, type SlopImageOptions } from "@slopmachine/core";
+  import {
+    buildImageUrl,
+    type SlopImageOptions,
+    type ImageAspectRatio,
+  } from "@slopmachine/core";
   import type { Snippet } from "svelte";
 
-  interface Props extends SlopImageOptions {
+  export interface SlopImageProps extends Omit<
+    SlopImageOptions,
+    "aspectRatio"
+  > {
+    /**
+     * The aspect ratio of the generated image. Defaults to "1:1".
+     */
+    aspectRatio?: ImageAspectRatio;
+    /**
+     * Additional CSS classes to apply to the wrapper element.
+     */
     class?: string;
+    /**
+     * Custom Svelte snippet to display while the image is loading.
+     * If not provided, a default spinner and shimmer effect will be shown.
+     */
     loader?: Snippet;
   }
 
@@ -18,7 +55,7 @@
     class: className = "",
     loader,
     ...restProps
-  }: Props = $props();
+  }: SlopImageProps = $props();
 
   let isLoading = $state(true);
 
@@ -96,51 +133,53 @@
   }
 </script>
 
-<div
-  class="slop-wrapper {className}"
-  style="aspect-ratio: {aspectRatio.replace(':', '/')};"
->
-  {#if isLoading}
-    {#if loader}
-      <div class="custom-loader-wrapper">
-        {@render loader()}
-      </div>
-    {:else}
-      <div class="loading-overlay">
-        <div class="spinner-container">
-          <svg
-            class="spinner"
-            xmlns="http://www.w3.org/2000/svg"
-            fill="none"
-            viewBox="0 0 24 24"
-          >
-            <circle
-              cx="12"
-              cy="12"
-              r="10"
-              stroke="currentColor"
-              stroke-width="4"
-            ></circle>
-            <path
-              fill="currentColor"
-              d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
-            ></path>
-          </svg>
-          <span>Loading...</span>
+<div class={className}>
+  <div
+    class="slop-wrapper"
+    style="aspect-ratio: {aspectRatio?.replace(':', '/')};"
+  >
+    {#if isLoading}
+      {#if loader}
+        <div class="custom-loader-wrapper">
+          {@render loader()}
         </div>
-      </div>
-      <div class="shimmer-effect"></div>
+      {:else}
+        <div class="loading-overlay">
+          <div class="spinner-container">
+            <svg
+              class="spinner"
+              xmlns="http://www.w3.org/2000/svg"
+              fill="none"
+              viewBox="0 0 24 24"
+            >
+              <circle
+                cx="12"
+                cy="12"
+                r="10"
+                stroke="currentColor"
+                stroke-width="4"
+              ></circle>
+              <path
+                fill="currentColor"
+                d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+              ></path>
+            </svg>
+            <span>Loading...</span>
+          </div>
+        </div>
+        <div class="shimmer-effect"></div>
+      {/if}
     {/if}
-  {/if}
-
-  <img
-    {src}
-    {alt}
-    onload={handleLoad}
-    onerror={handleError}
-    class:loaded={!isLoading}
-    {...restProps}
-  />
+
+    <img
+      {src}
+      {alt}
+      onload={handleLoad}
+      onerror={handleError}
+      class:loaded={!isLoading}
+      {...restProps}
+    />
+  </div>
 </div>
 
 <style>

package/src/SlopVideo.svelte

@@ -0,0 +1,296 @@
+<!--
+  @component
+  Renders a video generated by Slop Machine.
+
+  This component automatically constructs the correct URL for the Slop Machine API,
+  displays a loading skeleton or custom loader while fetching, and handles errors.
+
+  @example
+  ```svelte
+  <SlopVideo
+    bucketId="my-bucket"
+    resultId="some-result"
+    aspectRatio="16:9"
+    class="rounded-lg"
+    autoplay
+    loop
+    muted
+  />
+  ```
+-->
+<script lang="ts">
+  import {
+    buildVideoUrl,
+    type SlopVideoOptions,
+    type VideoAspectRatio,
+  } from "@slopmachine/core";
+  import type { Snippet } from "svelte";
+
+  export interface SlopVideoProps extends Omit<
+    SlopVideoOptions,
+    "aspectRatio"
+  > {
+    /**
+     * The aspect ratio of the generated video. Defaults to "16:9".
+     */
+    aspectRatio?: VideoAspectRatio;
+    /**
+     * Additional CSS classes to apply to the wrapper element.
+     */
+    class?: string;
+    /**
+     * Custom Svelte snippet to display while the video is loading.
+     * If not provided, a default spinner and shimmer effect will be shown.
+     */
+    loader?: Snippet;
+    autoplay?: boolean;
+    loop?: boolean;
+    muted?: boolean;
+    playsinline?: boolean;
+    [key: string]: any;
+  }
+
+  let {
+    bucketId,
+    aspectRatio = "16:9",
+    version,
+    resultId,
+    model,
+    variables = {},
+    duration,
+    baseUrl = undefined,
+    class: className = "",
+    loader,
+    autoplay = true,
+    loop = true,
+    muted = true,
+    playsinline = true,
+    ...restProps
+  }: SlopVideoProps = $props();
+
+  let isLoading = $state(true);
+
+  let computedSrc = $derived(
+    buildVideoUrl({
+      bucketId,
+      aspectRatio,
+      version,
+      resultId,
+      variables,
+      duration,
+      baseUrl,
+      model,
+    }),
+  );
+  let src = $state("");
+  let prevSrc = $state("");
+
+  $effect(() => {
+    const currentComputedSrc = computedSrc;
+    const timeout = setTimeout(() => {
+      if (src !== currentComputedSrc) {
+        src = currentComputedSrc;
+      }
+    }, 50);
+
+    return () => clearTimeout(timeout);
+  });
+
+  $effect(() => {
+    if (src !== prevSrc) {
+      isLoading = true;
+      prevSrc = src;
+    }
+  });
+
+  $effect(() => {
+    if (src) {
+      const abortController = new AbortController();
+      fetch(src, { method: "HEAD", signal: abortController.signal })
+        .then(async (res) => {
+          if (!res.ok) {
+            try {
+              const errRes = await fetch(src, {
+                signal: abortController.signal,
+              });
+              const errJson = await errRes.json();
+              console.error("SlopVideo error:", res.status, errJson.error);
+            } catch (e: any) {
+              if (e.name !== "AbortError") {
+                // Failed to fetch or parse error details
+              }
+            }
+            isLoading = false;
+          }
+        })
+        .catch((err) => {
+          if (err.name !== "AbortError") {
+            console.error(`Error fetching video from ${src}:`, err);
+            isLoading = false;
+          }
+        });
+
+      return () => abortController.abort();
+    }
+  });
+
+  function handleLoadedData() {
+    isLoading = false;
+  }
+
+  function handleError() {
+    isLoading = false;
+  }
+</script>
+
+<div class={className}>
+  <div
+    class="slop-wrapper"
+    style="aspect-ratio: {aspectRatio?.replace(':', '/')};"
+  >
+    {#if isLoading}
+      {#if loader}
+        <div class="custom-loader-wrapper">
+          {@render loader()}
+        </div>
+      {:else}
+        <div class="loading-overlay">
+          <div class="spinner-container">
+            <svg
+              class="spinner"
+              xmlns="http://www.w3.org/2000/svg"
+              fill="none"
+              viewBox="0 0 24 24"
+            >
+              <circle
+                cx="12"
+                cy="12"
+                r="10"
+                stroke="currentColor"
+                stroke-width="4"
+              ></circle>
+              <path
+                fill="currentColor"
+                d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+              ></path>
+            </svg>
+            <span>Loading...</span>
+          </div>
+        </div>
+        <div class="shimmer-effect"></div>
+      {/if}
+    {/if}
+
+    <!-- svelte-ignore a11y_media_has_caption -->
+    <video
+      {src}
+      {autoplay}
+      {loop}
+      {muted}
+      {playsinline}
+      onloadeddata={handleLoadedData}
+      onerror={handleError}
+      class:loaded={!isLoading}
+      {...restProps}
+    ></video>
+  </div>
+</div>
+
+<style>
+  .slop-wrapper {
+    position: relative;
+    overflow: hidden;
+    background-color: var(--muted, #f3f4f6);
+    width: 100%;
+    height: 100%;
+  }
+
+  .loading-overlay,
+  .custom-loader-wrapper {
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    z-index: 10;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: opacity 300ms ease-in-out;
+  }
+
+  .loading-overlay {
+    background-color: var(--muted, #f3f4f6);
+  }
+
+  .spinner-container {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  .spinner {
+    width: 24px;
+    height: 24px;
+    color: var(--muted-foreground, #6b7280);
+    animation: slop-spin 1s linear infinite;
+  }
+  .spinner circle {
+    opacity: 0.25;
+  }
+  .spinner path {
+    opacity: 0.75;
+  }
+
+  .spinner-container span {
+    font-size: 0.75rem;
+    color: var(--muted-foreground, #6b7280);
+  }
+
+  .shimmer-effect {
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background: linear-gradient(
+      90deg,
+      var(--muted, #f3f4f6) 0%,
+      var(--muted-foreground, #e5e7eb) 50%,
+      var(--muted, #f3f4f6) 100%
+    );
+    background-size: 200% 100%;
+    animation: slop-shimmer 2s ease-in-out infinite;
+  }
+
+  video {
+    height: 100%;
+    width: 100%;
+    object-fit: cover;
+    transition: opacity 500ms;
+    opacity: 0;
+  }
+
+  video.loaded {
+    opacity: 1;
+  }
+
+  @keyframes slop-shimmer {
+    0% {
+      background-position: 200% 0;
+    }
+    100% {
+      background-position: -200% 0;
+    }
+  }
+
+  @keyframes slop-spin {
+    from {
+      transform: rotate(0deg);
+    }
+    to {
+      transform: rotate(360deg);
+    }
+  }
+</style>

package/src/index.ts

@@ -1 +1,8 @@
-export { default as SlopImage } from "./SlopImage.svelte";
+export { default as SlopImage, type SlopImageProps } from "./SlopImage.svelte";
+export { default as SlopVideo, type SlopVideoProps } from "./SlopVideo.svelte";
+export type {
+  ImageAspectRatio,
+  VideoAspectRatio,
+  SlopImageOptions,
+  SlopVideoOptions,
+} from "@slopmachine/core";