Inject the credits state from main app instead

shared component for tutorials

app:
- tutorial modal accessible from any page on the app on the bottom right
- plays right in the modal through youtube embed
- it remembers the play progress and saves it in the zustand state so in
that current session if modal is opened again, it will continue where
the user left off

website:
- navbar updates (home and tutorials link)
- tutorial page with category buttons to filter by product or show all
- plays through youtube embed on website page

.gitignore

@@ -45,6 +45,9 @@ crates/lib/sqlite_queries/target/
 # Javascript build directories
 node_modules/
 
+# Frontend build outputs
+frontend/apps/editor3d/bundle-report.html
+
 # Vim noise
 *.swo
 *.swp

.sqlx/query-b48490837d568002305551353704c8e8a4fc78459e5a9aa754277b989107bc5c.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO analytics_app_active_users\nSET\n  app_namespace = ?,\n  user_token = ?,\n  app_version = ?,\n  os_platform = ?,\n  os_version = ?,\n  session_duration_seconds = ?,\n  ip_address = ?,\n  measurement_count = measurement_count + 1,\n  first_active_at = NOW(),\n  last_active_at = NOW()\nON DUPLICATE KEY UPDATE\n  app_version = ?,\n  os_platform = ?,\n  os_version = ?,\n  session_duration_seconds = ?,\n  ip_address = ?,\n  measurement_count = measurement_count + 1,\n  last_active_at = NOW()\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 12
+    },
+    "nullable": []
+  },
+  "hash": "b48490837d568002305551353704c8e8a4fc78459e5a9aa754277b989107bc5c"
+}

.sqlx/query-ff39576a5ec6a23c67f6f61e7eba8392e70b05c42b540bea260a9a4cdc478a5b.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO analytics_app_sessions\nSET\n  session_token = ?,\n  app_namespace = ?,\n  user_token = ?,\n  app_version = ?,\n  os_platform = ?,\n  os_version = ?,\n  session_duration_seconds = ?,\n  ip_address = ?,\n  measurement_count = measurement_count + 1,\n  first_active_at = NOW(),\n  last_active_at = NOW()\nON DUPLICATE KEY UPDATE\n  app_namespace = ?,\n  user_token = ?,\n  app_version = ?,\n  os_platform = ?,\n  os_version = ?,\n  session_duration_seconds = ?,\n  ip_address = ?,\n  measurement_count = measurement_count + 1,\n  last_active_at = NOW()\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 15
+    },
+    "nullable": []
+  },
+  "hash": "ff39576a5ec6a23c67f6f61e7eba8392e70b05c42b540bea260a9a4cdc478a5b"
+}

Cargo.toml

@@ -6,7 +6,8 @@ resolver = "2"
 members = [
   # API clients for external services
   # These might be custom implementations or wrappers over other client libraries.
-  "crates/api_clients/artcraft_api_defs", # TODO: api_clients/{artcraft}/{api_defs,client}
+  "crates/api_clients/artcraft/artcraft_api_defs", # TODO: api_clients/{artcraft}/{api_defs,client}
+  "crates/api_clients/artcraft/storyteller_client",
   "crates/api_clients/cloud_storage",
   "crates/api_clients/fal_client",
   "crates/api_clients/google_drive_common",
@@ -15,7 +16,6 @@ members = [
   "crates/api_clients/openai_sora_client",
   "crates/api_clients/openart_client",
   "crates/api_clients/runwayml_client",
-  "crates/api_clients/storyteller_client",
   "crates/api_clients/thumbnail_generator",
 
   # CLI tools for operations, etc.
@@ -181,7 +181,7 @@ workspace-build-acceleration = { path = "crates/workspace-build-acceleration" }
 # Internal libs
 # Setting paths here ensures we don't need to do so in every crate's Cargo.toml
 # It makes refactoring much easier.
-artcraft_api_defs = { path = "crates/api_clients/artcraft_api_defs" }
+artcraft_api_defs = { path = "crates/api_clients/artcraft/artcraft_api_defs" }
 build_metadata = { path = "crates/lib/build_metadata" }
 cloud_storage = { path = "crates/api_clients/cloud_storage" }
 cloudflare_errors = { path = "crates/lib/cloudflare_errors" }
@@ -205,7 +205,7 @@ openai_sora_client = { path = "crates/api_clients/openai_sora_client" }
 primitives = { path = "crates/lib/data/primitives" }
 shared_service_components = { path = "crates/lib/shared_service_components" }
 sqlite_tasks = { path = "crates/schema/database/sqlite_tasks" }
-storyteller_client = { path = "crates/api_clients/storyteller_client" }
+storyteller_client = { path = "crates/api_clients/artcraft/storyteller_client" }
 subprocess_common = { path = "crates/lib/subprocess_common" }
 test_data = { path = "crates/lib/test_data" }
 testing = { path = "crates/lib/testing" }
@@ -237,7 +237,7 @@ log = "0.4.27"
 once_cell = "1.21.3"
 rand = "0.9.1"
 regex = "1.11.1"
-reqwest = { version = "0.12.22", features = ["json", "cookies"] }
+reqwest = { version = "0.12.23", features = ["json", "cookies"] }
 reqwest-websocket = {  version = "0.5.0" }
 serde = {  version = "1.0.219", features = ["derive"] }
 serde_derive = "1.0.219"
@@ -255,3 +255,16 @@ thiserror = "2.0.12"
 tokio = { version = "1.45.1", features = ["macros"] }
 toml = "0.8.22"
 url = { version = "2.5.4", features = ["serde"] }
+
+# NB: wreq gets past fingerprinting, but we have to deal with platform-specific build issues.
+#
+# Mac:
+#   brew install --formula cmake pkg-config llvm
+# Windows:
+#   choco install cmake -y
+#   choco install strawberryperl -y
+#   choco install pkgconfiglite -y
+#   choco install llvm -y
+#   choco install nasm -y
+wreq = { version = "6.0.0-rc.20", features = ["json", "multipart", "cookies"] }
+wreq-util = "3.0.0-rc.5"

_sql/migrations/2025-09-24-055943_analytics_app_active_users/down.sql

@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+drop table analytics_app_active_users;

_sql/migrations/2025-09-24-055943_analytics_app_active_users/up.sql

@@ -0,0 +1,59 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+-- Track user activity over time
+-- User clients ping the endpoint that writes this data.
+CREATE TABLE analytics_app_active_users (
+  -- Not used for anything except replication.
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  -- If we host multiple sites with distinct categories, this will enable us to
+  -- segregate analytics.
+  app_namespace VARCHAR(32) NOT NULL,
+
+  -- Who sent the event.
+  user_token VARCHAR(32) NOT NULL,
+
+  -- Updated on every write.
+  -- The "user agent" or app version string of the client.
+  app_version VARCHAR(255) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The OS platform for the client.
+  os_platform VARCHAR(16) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The OS platform version for the client.
+  os_version VARCHAR(64) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- How long the current user's session has been open
+  session_duration_seconds INT(10) UNSIGNED DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The user's last known IP address.
+  ip_address VARCHAR(40) NOT NULL,
+
+  -- Incrementing count of events.
+  -- NB: This is kind of an "hours spent" measure, but will lose information if we ever
+  -- change the ping cadence (eg. 1 minute pings --> 5 minute pings).
+  measurement_count BIGINT UNSIGNED NOT NULL DEFAULT 0,
+
+  -- ========== RECORD TIMESTAMPS ==========
+
+  -- Written at create only.
+  first_active_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- Updated on every ping.
+  last_active_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- ========== INDICES ==========
+  PRIMARY KEY (id),
+  UNIQUE KEY (app_namespace, user_token), -- For now
+  INDEX idx_os_platform (os_platform),
+  INDEX idx_os_version (os_version),
+  INDEX idx_app_version (app_version),
+  INDEX idx_last_active_at (last_active_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_sql/migrations/2025-09-27-211355_analytics_app_sessions/down.sql

@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+drop table analytics_app_sessions;

_sql/migrations/2025-09-27-211355_analytics_app_sessions/up.sql

@@ -0,0 +1,65 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+-- Track user session durations
+-- User clients ping the endpoint that writes this data.
+CREATE TABLE analytics_app_sessions (
+  -- Not used for anything except replication.
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  -- Generated client-side
+  -- Wide enough for a UUID, but typically one of our internal tokens.
+  session_token VARCHAR(36) NOT NULL,
+
+  -- If we host multiple sites with distinct categories, this will enable us to
+  -- segregate analytics.
+  app_namespace VARCHAR(32) NOT NULL,
+
+  -- Who sent the event.
+  user_token VARCHAR(32) NOT NULL,
+
+  -- Updated on every write.
+  -- The "user agent" or app version string of the client.
+  app_version VARCHAR(255) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The OS platform for the client.
+  os_platform VARCHAR(16) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The OS platform version for the client.
+  os_version VARCHAR(64) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- How long the current user's session has been open
+  session_duration_seconds INT(10) UNSIGNED DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The user's last known IP address.
+  ip_address VARCHAR(40) NOT NULL,
+
+  -- Incrementing count of events.
+  -- NB: This is kind of an "hours spent" measure, but will lose information if we ever
+  -- change the ping cadence (eg. 1 minute pings --> 5 minute pings).
+  measurement_count BIGINT UNSIGNED NOT NULL DEFAULT 0,
+
+  -- ========== RECORD TIMESTAMPS ==========
+
+  -- Written at create only.
+  first_active_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- Updated on every ping.
+  last_active_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- ========== INDICES ==========
+  PRIMARY KEY (id),
+  UNIQUE KEY (session_token),
+  INDEX idx_app_namespace (app_namespace),
+  INDEX idx_user_token (user_token),
+  INDEX idx_os_platform (os_platform),
+  INDEX idx_os_version (os_version),
+  INDEX idx_app_version (app_version),
+  INDEX idx_last_active_at (last_active_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_sql/migrations_squashed/analytics/analytics_app_active_users.sql

@@ -0,0 +1,57 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE analytics_app_active_users (
+  -- Not used for anything except replication.
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  -- If we host multiple sites with distinct categories, this will enable us to
+  -- segregate analytics.
+  app_namespace VARCHAR(32) NOT NULL,
+
+  -- Who sent the event.
+  user_token VARCHAR(32) NOT NULL,
+
+  -- Updated on every write.
+  -- The "user agent" or app version string of the client.
+  app_version VARCHAR(255) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The OS platform for the client.
+  os_platform VARCHAR(16) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The OS platform version for the client.
+  os_version VARCHAR(64) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- How long the current user's session has been open
+  session_duration_seconds INT(10) UNSIGNED DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The user's last known IP address.
+  ip_address VARCHAR(40) NOT NULL,
+
+  -- Incrementing count of events.
+  -- NB: This is kind of an "hours spent" measure, but will lose information if we ever
+  -- change the ping cadence (eg. 1 minute pings --> 5 minute pings).
+  measurement_count BIGINT UNSIGNED NOT NULL DEFAULT 0,
+
+  -- ========== RECORD TIMESTAMPS ==========
+
+  -- Written at create only.
+  first_active_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- Updated on every ping.
+  last_active_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- ========== INDICES ==========
+  PRIMARY KEY (id),
+  UNIQUE KEY (app_namespace, user_token), -- For now
+  INDEX idx_app_version (app_version),
+  INDEX idx_os_platform (os_platform),
+  INDEX idx_os_version (os_version),
+  INDEX idx_last_active_at (last_active_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_sql/migrations_squashed/analytics/analytics_app_sessions.sql

@@ -0,0 +1,65 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+-- Track user session durations
+-- User clients ping the endpoint that writes this data.
+CREATE TABLE analytics_app_sessions (
+  -- Not used for anything except replication.
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  -- Generated client-side
+  -- Wide enough for a UUID, but typically one of our internal tokens.
+  session_token VARCHAR(36) NOT NULL,
+
+  -- If we host multiple sites with distinct categories, this will enable us to
+  -- segregate analytics.
+  app_namespace VARCHAR(32) NOT NULL,
+
+  -- Who sent the event.
+  user_token VARCHAR(32) NOT NULL,
+
+  -- Updated on every write.
+  -- The "user agent" or app version string of the client.
+  app_version VARCHAR(255) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The OS platform for the client.
+  os_platform VARCHAR(16) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The OS platform version for the client.
+  os_version VARCHAR(64) DEFAULT NULL,
+
+  -- Updated on every write.
+  -- How long the current user's session has been open
+  session_duration_seconds INT(10) UNSIGNED DEFAULT NULL,
+
+  -- Updated on every write.
+  -- The user's last known IP address.
+  ip_address VARCHAR(40) NOT NULL,
+
+  -- Incrementing count of events.
+  -- NB: This is kind of an "hours spent" measure, but will lose information if we ever
+  -- change the ping cadence (eg. 1 minute pings --> 5 minute pings).
+  measurement_count BIGINT UNSIGNED NOT NULL DEFAULT 0,
+
+  -- ========== RECORD TIMESTAMPS ==========
+
+  -- Written at create only.
+  first_active_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- Updated on every ping.
+  last_active_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- ========== INDICES ==========
+  PRIMARY KEY (id),
+  UNIQUE KEY (session_token),
+  INDEX idx_app_namespace (app_namespace),
+  INDEX idx_user_token (user_token),
+  INDEX idx_os_platform (os_platform),
+  INDEX idx_os_version (os_version),
+  INDEX idx_app_version (app_version),
+  INDEX idx_last_active_at (last_active_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_sql/migrations_squashed/user_tables/users.sql

@@ -186,8 +186,8 @@ CREATE TABLE users (
   -- ========== TRACKING ==========
 
   -- Where the user signed up from (NOT NECESSARILY AN ENUM!)
-  -- For now this will be "fakeyou" and "storyteller", but we may extend
-  -- or overload this to handle other cases or metadata.
+  -- For now this will be "artcraft", "fakeyou", or "storyteller", 
+  -- though we may extend or overload this to handle other cases or metadata.
   maybe_source VARCHAR(255) DEFAULT NULL,
 
   -- How users created their account

crates/api_clients/artcraft/artcraft_api_defs/src/analytics/log_active_user.rs

@@ -0,0 +1,40 @@
+use serde_derive::{Deserialize, Serialize};
+use tokens::tokens::app_session::AppSessionToken;
+use utoipa::ToSchema;
+
+pub const LOG_ACTIVE_USER_PATH: &str = "/v1/analytics/active_user";
+
+#[derive(Serialize, Deserialize, ToSchema, Debug)]
+pub struct LogAppActiveUserRequest {
+  /// Clientside-generated session token.
+  /// If present, it'll be validated against an expected format.
+  pub maybe_app_session_token: Option<AppSessionToken>,
+  
+  /// An override for the application platform/OS (windows, mac, linux).
+  pub maybe_os_platform: Option<String>,
+
+  /// An override for the version of the OS (e.g. 10.15.7, 11, 22.04).
+  pub maybe_os_version: Option<String>,
+
+  /// An override for the application name.
+  /// If set together with `maybe_app_version`, the two will be 
+  /// concatenated as `{maybe_app_name}/{maybe_app_version}`.
+  pub maybe_app_name: Option<String>,
+
+  /// An override for the application version.
+  /// If set together with `maybe_app_name`, the two will be 
+  /// concatenated as `{maybe_app_name}/{maybe_app_version}`.
+  pub maybe_app_version: Option<String>,
+  
+  /// How long the user has been active in the app, in seconds.
+  pub maybe_session_duration_seconds: Option<u64>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct LogAppActiveUserResponse {
+  pub success: bool,
+  
+  /// How long to wait until the next analytics event, in milliseconds.
+  /// The client should honor this and is free to add jitter.
+  pub wait_for_retry_millis: u64,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/analytics/mod.rs

@@ -0,0 +1 @@
+pub mod log_active_user;

crates/api_clients/artcraft/artcraft_api_defs/src/common/responses/mod.rs

@@ -3,4 +3,5 @@ pub mod job_details;
 pub mod media_file_cover_image_details;
 pub mod media_links;
 pub mod simple_entity_stats;
+pub mod simple_generic_json_success;
 pub mod user_details_light;

crates/api_clients/artcraft/artcraft_api_defs/src/common/responses/simple_generic_json_success.rs

@@ -0,0 +1,7 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct SimpleGenericJsonSuccess {
+  pub success: bool,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/lib.rs

@@ -1,3 +1,4 @@
+pub mod analytics;
 pub mod common;
 pub mod credits;
 pub mod generate;

crates/api_clients/artcraft/artcraft_api_defs/src/media_file/delete_media_file.rs

@@ -0,0 +1,19 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+use tokens::tokens::media_files::MediaFileToken;
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct DeleteMediaFileRequest {
+  pub set_delete: bool,
+  
+  /// NB: this is only to disambiguate when a user is both a mod and an author.
+  pub as_mod: Option<bool>,
+}
+
+/// For the URL PathInfo
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct DeleteMediaFilePathInfo {
+  pub token: MediaFileToken,
+}
+
+

crates/api_clients/artcraft/artcraft_api_defs/src/media_file/mod.rs

@@ -1 +1,2 @@
+pub mod delete_media_file;
 pub mod list_batch_generated_media_files;

crates/api_clients/artcraft/storyteller_client/Cargo.toml

@@ -46,8 +46,11 @@ serde_derive.workspace = true
 serde_json.workspace = true
 
 # HTTP
-backoff = { version = "0.4.0", features = ["futures"] }
-uuid = { version = "1.8.0", features = ["v4"] } # Exponential backoff retry
+backoff = { version = "0.4.0", features = ["futures"] }  # Exponential backoff retry
+uuid = { version = "1.8.0", features = ["v4"] }
+
+# TODO: This is not a very mature, safe, or intuitive URL builder library. Please replace it!
+url-builder = "0.1.1"
 
 [dev-dependencies]
 tokio.workspace = true

crates/api_clients/artcraft/storyteller_client/src/endpoints/analytics/log_active_user.rs

@@ -0,0 +1,48 @@
+use crate::credentials::storyteller_credential_set::StorytellerCredentialSet;
+use crate::error::storyteller_error::StorytellerError;
+use crate::utils::api_host::ApiHost;
+use crate::utils::basic_query_string_post_request::basic_query_string_post_request;
+use artcraft_api_defs::analytics::log_active_user::{LogAppActiveUserRequest, LogAppActiveUserResponse, LOG_ACTIVE_USER_PATH};
+use std::collections::HashMap;
+
+pub async fn log_active_user(
+  api_host: &ApiHost,
+  maybe_creds: Option<&StorytellerCredentialSet>,
+  request: LogAppActiveUserRequest,
+) -> Result<LogAppActiveUserResponse, StorytellerError> {
+
+  // TODO(bt): This is gross and doesn't automatically handle field changes.
+  
+  let mut query = HashMap::new();
+
+  if let Some(token) = request.maybe_app_session_token {
+    query.insert("maybe_app_session_token".to_string(), token.to_string());
+  }
+
+  if let Some(os_platform) = request.maybe_os_platform {
+    query.insert("maybe_os_platform".to_string(), os_platform);
+  }
+  
+  if let Some(os_version) = request.maybe_os_version {
+    query.insert("maybe_os_version".to_string(), os_version);
+  }
+  
+  if let Some(app_name) = request.maybe_app_name {
+    query.insert("maybe_app_name".to_string(), app_name);
+  }
+  
+  if let Some(app_version) = request.maybe_app_version {
+    query.insert("maybe_app_version".to_string(), app_version);
+  }
+  
+  if let Some(maybe_session_duration_seconds) = request.maybe_session_duration_seconds {
+    query.insert("maybe_session_duration_seconds".to_string(), maybe_session_duration_seconds.to_string());
+  }
+
+  Ok(basic_query_string_post_request(
+    api_host,
+    LOG_ACTIVE_USER_PATH,
+    maybe_creds,
+    &query,
+  ).await?)
+}

crates/api_clients/artcraft/storyteller_client/src/endpoints/analytics/mod.rs

@@ -0,0 +1 @@
+pub mod log_active_user;