@pylonsync/create-pylon 0.19.0 → 0.20.0

package/templates/ios/consumer/apps/ios/Sources/__APP_NAME_PASCAL__/SocialStore.swift

@@ -0,0 +1,285 @@
+import Combine
+import Foundation
+import PylonClient
+import PylonSync
+import PylonSwiftUI
+
+/// The live social graph. Five subscriptions (Profile, Post, Like, Comment,
+/// Follow) on the sync engine, joined in memory. A row written by any
+/// client reaches every open app over the engine's WebSocket, and every
+/// view that reads this store redraws.
+///
+/// Writes go through server functions. The server writes the row, the
+/// change comes back through sync, and the view updates. Likes and follows
+/// also show at once through a pending state that clears when the synced
+/// row arrives.
+@MainActor
+final class SocialStore: ObservableObject {
+	let engine: SyncEngine
+	let client: PylonClient
+	let media: MediaService
+
+	@Published var myProfileId: String?
+	@Published private(set) var profiles: [String: Profile] = [:]
+	/// Newest first.
+	@Published private(set) var posts: [Post] = []
+	@Published private(set) var likesByPost: [String: [Like]] = [:]
+	/// Oldest first within a post.
+	@Published private(set) var commentsByPost: [String: [Comment]] = [:]
+	@Published private(set) var follows: [Follow] = []
+	@Published private(set) var isLoading = true
+	/// Post ids the user liked or unliked whose synced row has not arrived yet.
+	@Published private(set) var pendingLikes: [String: Bool] = [:]
+	@Published private(set) var pendingFollows: [String: Bool] = [:]
+
+	private let profileQuery: PylonQuery<Profile>
+	private let postQuery: PylonQuery<Post>
+	private let likeQuery: PylonQuery<Like>
+	private let commentQuery: PylonQuery<Comment>
+	private let followQuery: PylonQuery<Follow>
+	private var subscriptions: Set<AnyCancellable> = []
+
+	init(engine: SyncEngine, client: PylonClient, media: MediaService) {
+		self.engine = engine
+		self.client = client
+		self.media = media
+		profileQuery = PylonQuery(engine: engine, entity: "Profile")
+		postQuery = PylonQuery(engine: engine, entity: "Post")
+		likeQuery = PylonQuery(engine: engine, entity: "Like")
+		commentQuery = PylonQuery(engine: engine, entity: "Comment")
+		followQuery = PylonQuery(engine: engine, entity: "Follow")
+
+		profileQuery.$rows
+			.sink { [weak self] rows in
+				self?.profiles = Dictionary(rows.map { ($0.id, $0) }, uniquingKeysWith: { _, new in new })
+			}
+			.store(in: &subscriptions)
+		postQuery.$rows
+			.sink { [weak self] rows in
+				self?.posts = rows.sorted { $0.createdAt > $1.createdAt }
+			}
+			.store(in: &subscriptions)
+		likeQuery.$rows
+			.sink { [weak self] rows in
+				guard let self else { return }
+				likesByPost = Dictionary(grouping: rows, by: \.postId)
+				pendingLikes = pendingLikes.filter { postId, liked in
+					self.syncedLike(postId) != liked
+				}
+			}
+			.store(in: &subscriptions)
+		commentQuery.$rows
+			.sink { [weak self] rows in
+				self?.commentsByPost = Dictionary(grouping: rows, by: \.postId)
+					.mapValues { $0.sorted { $0.createdAt < $1.createdAt } }
+			}
+			.store(in: &subscriptions)
+		followQuery.$rows
+			.sink { [weak self] rows in
+				guard let self else { return }
+				follows = rows
+				pendingFollows = pendingFollows.filter { profileId, following in
+					self.syncedFollow(profileId) != following
+				}
+			}
+			.store(in: &subscriptions)
+		postQuery.$loading
+			.sink { [weak self] loading in self?.isLoading = loading }
+			.store(in: &subscriptions)
+	}
+
+	// MARK: - Reads
+
+	var me: Profile? { myProfileId.flatMap { profiles[$0] } }
+
+	func profile(_ id: String) -> Profile? { profiles[id] }
+
+	func posts(by profileId: String) -> [Post] {
+		posts.filter { $0.authorId == profileId }
+	}
+
+	func post(_ id: String) -> Post? { posts.first { $0.id == id } }
+
+	func isLiked(_ postId: String) -> Bool {
+		pendingLikes[postId] ?? syncedLike(postId)
+	}
+
+	func likeCount(_ postId: String) -> Int {
+		let synced = likesByPost[postId]?.count ?? 0
+		guard let pending = pendingLikes[postId], pending != syncedLike(postId) else { return synced }
+		return synced + (pending ? 1 : -1)
+	}
+
+	/// A liker to name under the photo: someone the user follows first, else the latest.
+	func featuredLiker(_ postId: String) -> Profile? {
+		let likes = (likesByPost[postId] ?? []).filter { $0.profileId != myProfileId }
+		let following = Set(followingIds(of: myProfileId))
+		let pick = likes.first { following.contains($0.profileId) } ?? likes.max { $0.createdAt < $1.createdAt }
+		return pick.flatMap { profiles[$0.profileId] }
+	}
+
+	func comments(_ postId: String) -> [Comment] { commentsByPost[postId] ?? [] }
+
+	func followerIds(of profileId: String) -> [String] {
+		follows.filter { $0.followingId == profileId }.map(\.followerId)
+	}
+
+	func followingIds(of profileId: String?) -> [String] {
+		guard let profileId else { return [] }
+		return follows.filter { $0.followerId == profileId }.map(\.followingId)
+	}
+
+	func isFollowing(_ profileId: String) -> Bool {
+		pendingFollows[profileId] ?? syncedFollow(profileId)
+	}
+
+	func followerCount(_ profileId: String) -> Int {
+		let synced = followerIds(of: profileId).count
+		guard let pending = pendingFollows[profileId], pending != syncedFollow(profileId) else { return synced }
+		return synced + (pending ? 1 : -1)
+	}
+
+	/// People with a post in the last 24 hours, the user first, then newest.
+	var storyAuthors: [Profile] {
+		let cutoff = Date.now.addingTimeInterval(-86_400)
+		var seen = Set<String>()
+		var out: [Profile] = []
+		for post in posts where post.date > cutoff {
+			guard !seen.contains(post.authorId), post.authorId != myProfileId,
+			      let author = profiles[post.authorId] else { continue }
+			seen.insert(post.authorId)
+			out.append(author)
+		}
+		return out
+	}
+
+	func hasRecentPost(_ profileId: String) -> Bool {
+		let cutoff = Date.now.addingTimeInterval(-86_400)
+		return posts.contains { $0.authorId == profileId && $0.date > cutoff }
+	}
+
+	func recentPosts(by profileId: String) -> [Post] {
+		let cutoff = Date.now.addingTimeInterval(-86_400)
+		return posts.filter { $0.authorId == profileId && $0.date > cutoff }.reversed()
+	}
+
+	/// Likes, comments, and follows aimed at the user, newest first.
+	var activity: [ActivityItem] {
+		guard let me = myProfileId else { return [] }
+		let mine = Set(posts.filter { $0.authorId == me }.map(\.id))
+		var items: [ActivityItem] = []
+		for postId in mine {
+			for like in likesByPost[postId] ?? [] where like.profileId != me {
+				items.append(ActivityItem(id: "like-\(like.id)", kind: .like, actorId: like.profileId, postId: postId, text: nil, createdAt: like.createdAt))
+			}
+			for comment in commentsByPost[postId] ?? [] where comment.profileId != me {
+				items.append(ActivityItem(id: "comment-\(comment.id)", kind: .comment, actorId: comment.profileId, postId: postId, text: comment.text, createdAt: comment.createdAt))
+			}
+		}
+		for follow in follows where follow.followingId == me {
+			items.append(ActivityItem(id: "follow-\(follow.id)", kind: .follow, actorId: follow.followerId, postId: nil, text: nil, createdAt: follow.createdAt))
+		}
+		return items.sorted { $0.createdAt > $1.createdAt }
+	}
+
+	private func syncedLike(_ postId: String) -> Bool {
+		guard let me = myProfileId else { return false }
+		return likesByPost[postId]?.contains { $0.profileId == me } ?? false
+	}
+
+	private func syncedFollow(_ profileId: String) -> Bool {
+		guard let me = myProfileId else { return false }
+		return follows.contains { $0.followerId == me && $0.followingId == profileId }
+	}
+
+	// MARK: - Writes
+
+	func toggleLike(_ postId: String) {
+		let next = !isLiked(postId)
+		setLike(postId, liked: next)
+	}
+
+	/// Double tap only ever likes.
+	func like(_ postId: String) {
+		if !isLiked(postId) { setLike(postId, liked: true) }
+	}
+
+	/// Records the tap at once, then sends the wanted state. The server call
+	/// sets the state rather than flipping it, so taps that arrive out of
+	/// order still end in the last tap's state.
+	private func setLike(_ postId: String, liked: Bool) {
+		pendingLikes[postId] = liked
+		Task {
+			do {
+				_ = try await client.callFn("setLike", args: SetLikeArgs(postId: postId, liked: liked), as: SetLikeResult.self)
+			} catch {
+				if pendingLikes[postId] == liked { pendingLikes[postId] = nil }
+			}
+		}
+	}
+
+	func toggleFollow(_ profileId: String) {
+		let following = !isFollowing(profileId)
+		pendingFollows[profileId] = following
+		Task {
+			do {
+				_ = try await client.callFn("setFollow", args: SetFollowArgs(profileId: profileId, following: following), as: SetFollowResult.self)
+			} catch {
+				if pendingFollows[profileId] == following { pendingFollows[profileId] = nil }
+			}
+		}
+	}
+
+	func addComment(_ postId: String, text: String) async throws {
+		_ = try await client.callFn("addComment", args: AddCommentArgs(postId: postId, text: text), as: IdResult.self)
+	}
+
+	func deletePost(_ postId: String) async throws {
+		_ = try await client.callFn("deletePost", args: DeletePostArgs(id: postId), as: IdResult.self)
+	}
+
+	func createPost(jpeg: Data, caption: String) async throws {
+		let imageUrl = try await media.uploadPublicJPEG(jpeg)
+		_ = try await client.callFn("createPost", args: CreatePostArgs(imageUrl: imageUrl, caption: caption), as: IdResult.self)
+	}
+
+	func saveProfile(handle: String, displayName: String, bio: String, avatarJPEG: Data?) async throws -> Profile {
+		var avatarUrl: String?
+		if let avatarJPEG {
+			avatarUrl = try await media.uploadPublicJPEG(avatarJPEG)
+		}
+		return try await client.callFn(
+			"upsertProfile",
+			args: UpsertProfileArgs(handle: handle, displayName: displayName, bio: bio, avatarUrl: avatarUrl),
+			as: Profile.self
+		)
+	}
+}
+
+struct ActivityItem: Identifiable, Hashable {
+	enum Kind { case like, comment, follow }
+	let id: String
+	let kind: Kind
+	let actorId: String
+	let postId: String?
+	let text: String?
+	let createdAt: String
+
+	var date: Date { Timestamp.parse(createdAt) }
+}
+
+/// A readable sentence for an error from a server function or the network.
+func friendlyMessage(_ error: Error) -> String {
+	if let pylon = error as? PylonError {
+		switch pylon {
+		case .http(_, _, let message?) where !message.isEmpty:
+			return message.prefix(1).uppercased() + message.dropFirst()
+		case .transport:
+			return "Cannot reach the server. Check your connection and try again."
+		default:
+			return "Something went wrong. Try again."
+		}
+	}
+	if let local = error as? LocalizedError, let text = local.errorDescription { return text }
+	return "Something went wrong. Try again."
+}

package/templates/ios/consumer/apps/ios/Sources/__APP_NAME_PASCAL__/StoryViewer.swift

@@ -0,0 +1,155 @@
+import SwiftUI
+
+/// Full-screen playback of each person's posts from the last 24 hours.
+/// Every photo shows for five seconds. Tap the right side for the next
+/// photo, the left side for the previous one, or swipe down to close.
+struct StoryViewer: View {
+	@EnvironmentObject private var social: SocialStore
+	@Environment(\.dismiss) private var dismiss
+
+	let authors: [Profile]
+	@State var authorIndex: Int
+	@State private var postIndex = 0
+	@State private var progress: Double = 0
+	@State private var dragOffset: CGFloat = 0
+	/// Bumped to replay the current photo from the start.
+	@State private var restarts = 0
+
+	private let duration: Double = 5
+	private let tick: Double = 0.05
+
+	init(authors: [Profile], startIndex: Int) {
+		self.authors = authors
+		_authorIndex = State(initialValue: startIndex)
+	}
+
+	private var author: Profile? { authors.indices.contains(authorIndex) ? authors[authorIndex] : nil }
+	private var posts: [Post] { author.map { social.recentPosts(by: $0.id) } ?? [] }
+	private var post: Post? { posts.indices.contains(postIndex) ? posts[postIndex] : nil }
+
+	var body: some View {
+		ZStack {
+			Color.black.ignoresSafeArea()
+			if let post {
+				let url = social.media.url(for: post.imageUrl)
+				RemoteImage(url: url)
+					.blur(radius: 40)
+					.opacity(0.6)
+					.ignoresSafeArea()
+				Color.clear
+					.aspectRatio(4 / 5, contentMode: .fit)
+					.overlay { RemoteImage(url: url) }
+					.clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
+					.id(post.id)
+			}
+			HStack(spacing: 0) {
+				Color.clear.contentShape(Rectangle()).onTapGesture(perform: previous)
+				Color.clear.contentShape(Rectangle()).onTapGesture(perform: next)
+			}
+			VStack(spacing: 10) {
+				progressBars
+				topBar
+				Spacer()
+				if let caption = post?.caption, !caption.isEmpty {
+					Text(caption)
+						.font(.subheadline)
+						.foregroundStyle(.white)
+						.multilineTextAlignment(.leading)
+						.frame(maxWidth: .infinity, alignment: .leading)
+						.padding(14)
+						.background(.black.opacity(0.35), in: RoundedRectangle(cornerRadius: 14, style: .continuous))
+				}
+			}
+			.padding(.horizontal, 12)
+			.padding(.top, 8)
+		}
+		.offset(y: dragOffset)
+		.gesture(
+			DragGesture()
+				.onChanged { value in dragOffset = max(0, value.translation.height) }
+				.onEnded { value in
+					if value.translation.height > 120 { dismiss() } else {
+						withAnimation(.spring) { dragOffset = 0 }
+					}
+				}
+		)
+		.statusBarHidden()
+		.task(id: "\(authorIndex)-\(postIndex)-\(restarts)") { await play() }
+	}
+
+	private var progressBars: some View {
+		HStack(spacing: 4) {
+			ForEach(posts.indices, id: \.self) { index in
+				GeometryReader { geo in
+					Capsule().fill(.white.opacity(0.35))
+						.overlay(alignment: .leading) {
+							Capsule().fill(.white)
+								.frame(width: geo.size.width * fill(for: index))
+						}
+				}
+				.frame(height: 2.5)
+			}
+		}
+	}
+
+	private var topBar: some View {
+		HStack(spacing: 10) {
+			AvatarView(profile: author, size: 32)
+			Text(author?.handle ?? "")
+				.font(.subheadline.weight(.semibold))
+			if let post {
+				Text(Timestamp.short(post.date))
+					.font(.subheadline)
+					.opacity(0.7)
+			}
+			Spacer()
+			Button { dismiss() } label: {
+				Image(systemName: "xmark")
+					.font(.system(size: 20, weight: .semibold))
+					.frame(width: 40, height: 40)
+					.contentShape(Rectangle())
+			}
+			.accessibilityLabel("Close")
+		}
+		.foregroundStyle(.white)
+	}
+
+	private func fill(for index: Int) -> Double {
+		if index < postIndex { return 1 }
+		if index == postIndex { return progress }
+		return 0
+	}
+
+	private func play() async {
+		progress = 0
+		let steps = Int(duration / tick)
+		for _ in 0..<steps {
+			try? await Task.sleep(for: .seconds(tick))
+			if Task.isCancelled { return }
+			progress += tick / duration
+		}
+		next()
+	}
+
+	private func next() {
+		if postIndex + 1 < posts.count {
+			postIndex += 1
+		} else if authorIndex + 1 < authors.count {
+			authorIndex += 1
+			postIndex = 0
+		} else {
+			dismiss()
+		}
+	}
+
+	private func previous() {
+		if postIndex > 0 {
+			postIndex -= 1
+		} else if authorIndex > 0 {
+			authorIndex -= 1
+			postIndex = 0
+		} else {
+			restarts += 1
+		}
+	}
+}

package/templates/ios/consumer/apps/ios/Sources/__APP_NAME_PASCAL__/Theme.swift

@@ -0,0 +1,82 @@
+import SwiftUI
+
+enum Theme {
+	/// Filled buttons, links, and badges. Fixed so the black tab bar tint
+	/// does not change it.
+	static let accent = Color(red: 0.0, green: 0.584, blue: 0.965)
+	/// The like color.
+	static let heart = Color(red: 1.0, green: 0.19, blue: 0.25)
+	/// The ring around an avatar with a post from the last 24 hours.
+	static let storyRing = AngularGradient(
+		colors: [
+			Color(red: 0.99, green: 0.73, blue: 0.27),
+			Color(red: 0.98, green: 0.38, blue: 0.20),
+			Color(red: 0.87, green: 0.15, blue: 0.47),
+			Color(red: 0.55, green: 0.22, blue: 0.85),
+			Color(red: 0.99, green: 0.73, blue: 0.27),
+		],
+		center: .center
+	)
+	static let hairline = Color(uiColor: .separator)
+	static let fieldFill = Color(uiColor: .secondarySystemBackground)
+}
+
+/// The app name in the feed header and on the sign-in screen.
+struct Wordmark: View {
+	var size: CGFloat = 30
+
+	var body: some View {
+		Text("__APP_NAME__")
+			.font(.system(size: size, weight: .semibold, design: .serif))
+			.italic()
+			.tracking(-0.5)
+	}
+}
+
+/// A full-width filled button for the main action on a screen.
+struct PrimaryButtonStyle: ButtonStyle {
+	var isLoading = false
+
+	func makeBody(configuration: Configuration) -> some View {
+		ZStack {
+			configuration.label.opacity(isLoading ? 0 : 1)
+			if isLoading { ProgressView().tint(.white) }
+		}
+		.font(.body.weight(.semibold))
+		.foregroundStyle(.white)
+		.frame(maxWidth: .infinity, minHeight: 50)
+		.background(Theme.accent, in: RoundedRectangle(cornerRadius: 12, style: .continuous))
+		.opacity(configuration.isPressed ? 0.8 : 1)
+	}
+}
+
+/// A compact button for profile actions: Edit profile, Follow, Following.
+struct ProfileButtonStyle: ButtonStyle {
+	var prominent = false
+
+	func makeBody(configuration: Configuration) -> some View {
+		configuration.label
+			.font(.subheadline.weight(.semibold))
+			.foregroundStyle(prominent ? Color.white : Color.primary)
+			.frame(maxWidth: .infinity, minHeight: 34)
+			.background(
+				prominent ? Theme.accent : Theme.fieldFill,
+				in: RoundedRectangle(cornerRadius: 9, style: .continuous)
+			)
+			.opacity(configuration.isPressed ? 0.7 : 1)
+	}
+}
+
+/// A rounded text field on the sign-in and profile screens.
+struct FieldStyle: ViewModifier {
+	func body(content: Content) -> some View {
+		content
+			.padding(.horizontal, 14)
+			.frame(minHeight: 50)
+			.background(Theme.fieldFill, in: RoundedRectangle(cornerRadius: 12, style: .continuous))
+	}
+}
+
+extension View {
+	func fieldStyle() -> some View { modifier(FieldStyle()) }
+}

package/templates/ios/consumer/apps/ios/Sources/__APP_NAME_PASCAL__/__APP_NAME_PASCAL__App.swift

@@ -1,57 +1,14 @@
 import SwiftUI
-import PylonClient
-import PylonSync
 
 @main
 struct __APP_NAME_PASCAL__App: App {
-	@StateObject private var session = AppSession()
+	@StateObject private var app = AppModel()
 
 	var body: some Scene {
 		WindowGroup {
-			Group {
-				if let engine = session.engine {
-					RootView(engine: engine)
-						.environmentObject(session)
-				} else {
-					ProgressView()
-						.frame(maxWidth: .infinity, maxHeight: .infinity)
-				}
-			}
-			.task { await session.bootIfNeeded() }
+			RootView()
+				.environmentObject(app)
+				.task { await app.boot() }
 		}
 	}
 }
-
-@MainActor
-final class AppSession: ObservableObject {
-	let client: PylonClient
-	@Published private(set) var engine: SyncEngine?
-	@Published var myProfileId: String?
-
-	init() {
-		let baseURLString = ProcessInfo.processInfo.environment["PYLON_BASE_URL"]
-			?? "http://localhost:4321"
-		guard let url = URL(string: baseURLString) else {
-			fatalError("Invalid PYLON_BASE_URL: \(baseURLString)")
-		}
-		self.client = PylonClient(baseURL: url, appName: "__APP_NAME_SNAKE__")
-		self.myProfileId = UserDefaults.standard.string(forKey: "myProfileId")
-	}
-
-	func bootIfNeeded() async {
-		guard engine == nil else { return }
-		let baseURLString = ProcessInfo.processInfo.environment["PYLON_BASE_URL"]
-			?? "http://localhost:4321"
-		guard let url = URL(string: baseURLString) else { return }
-		let config = SyncEngineConfig(baseURL: url, appName: "__APP_NAME_SNAKE__")
-		let engine = await SyncEngine(config: config, client: client)
-		await engine.start()
-		self.engine = engine
-	}
-
-	func setMyProfileId(_ id: String?) {
-		myProfileId = id
-		if let id { UserDefaults.standard.set(id, forKey: "myProfileId") }
-		else { UserDefaults.standard.removeObject(forKey: "myProfileId") }
-	}
-}

package/templates/ios/consumer/apps/ios/project.yml

@@ -3,18 +3,24 @@
 # Materialize the Xcode project once with:
 #     brew install xcodegen
 #     xcodegen generate
-# Then open __APP_NAME_PASCAL__.xcodeproj.
+# Then open __APP_NAME_PASCAL__.xcodeproj. Run xcodegen again after you add
+# or remove Swift files.
+#
+# The app talks to the Pylon backend in apps/api. Start it with `pylon dev`
+# there. The simulator reaches http://localhost:4321; on a device, set
+# PYLON_BASE_URL in the scheme's environment to your Mac's LAN address or
+# your deployed API.
 
 name: __APP_NAME_PASCAL__
 options:
   bundleIdPrefix: com.example
   deploymentTarget:
-    iOS: "16.0"
+    iOS: "17.0"
 
 packages:
   pylon:
     url: https://github.com/pylonsync/pylon.git
-    from: "0.3.0"
+    from: "__PYLON_VERSION__"
 
 targets:
   __APP_NAME_PASCAL__:
@@ -25,15 +31,13 @@ targets:
     settings:
       base:
         GENERATE_INFOPLIST_FILE: YES
+        INFOPLIST_KEY_CFBundleDisplayName: "__APP_NAME__"
         INFOPLIST_KEY_UIApplicationSceneManifest_Generation: YES
         INFOPLIST_KEY_UILaunchScreen_Generation: YES
-        INFOPLIST_KEY_UISupportedInterfaceOrientations: "UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight"
-        TARGETED_DEVICE_FAMILY: "1,2"
-        SWIFT_VERSION: "5.9"
+        INFOPLIST_KEY_UISupportedInterfaceOrientations: "UIInterfaceOrientationPortrait"
+        TARGETED_DEVICE_FAMILY: "1"
+        SWIFT_VERSION: "5.0"
         ENABLE_PREVIEWS: YES
-        # __APP_NAME__ talks to a Pylon backend on localhost during dev.
-        # The simulator can reach localhost directly; on a physical device
-        # set PYLON_BASE_URL to your machine's LAN IP.
         INFOPLIST_KEY_NSAppTransportSecurity: "{NSAllowsLocalNetworking = YES;}"
     dependencies:
       - package: pylon

package/templates/local-service/.env.example

@@ -10,3 +10,10 @@ PYLON_OWNER_EMAIL=you@yourshop.com
 # ── Site URL (optional) ──────────────────────────────────────────────────────
 # Used by robots.txt + sitemap.xml. Point it at your real domain in production.
 # SITE_URL=https://yourshop.com
+
+# ── Demo data ────────────────────────────────────────────────────────────────
+# `pylon dev` fills an empty booking book with fictional appointments. Seeding
+# runs only under `pylon dev` (it checks PYLON_DEV_MODE and
+# PYLON_DEV_WATCH_DIR), so `pylon start`, Docker, and Pylon Cloud deploys never
+# seed. Set 0 to start empty in development. Never set 1 on a deploy.
+# PYLON_DEMO_DATA=0

package/templates/local-service/README.md

@@ -45,6 +45,23 @@ Set `PYLON_OWNER_EMAIL` in `.env` (see `.env.example`) to the email you'll sign
 in with, then create that account at `/login`. Only that account can see
 bookings.
 
+## Demo data
+
+In `pylon dev`, an empty booking book gets fictional appointments from the past
+week and the next ten days (`functions/seedDemo.ts`, `lib/demo.ts`). Each one
+writes a `Booking` and its `BookedSlot`, like a real booking, so the public grid
+shows those times as booked and the dashboard lists them. Seeding runs only
+when `PYLON_DEMO_DATA` is on, or when it is unset and the app runs under `pylon dev`,
+and only while the `Booking` table is empty. `pylon start`, Docker, and Pylon Cloud deploys do not seed, because only `pylon dev` sets `PYLON_DEV_WATCH_DIR`. Set `PYLON_DEMO_DATA=0` to start empty in
+development. Delete both files once you take real bookings.
+
+## Map or hours board
+
+Set `location.mapEmbedUrl` in `lib/site.config.ts` to a Google Maps embed URL to
+show a map beside the address. Without one, the site shows the weekly hours
+(from `booking.hours`, the same hours the booking grid uses) and a directions
+link. The dashboard reminds you while the URL is empty.
+
 ## Rebrand + reconfigure it
 
 Brand, colors, services, weekly hours, slot length, lead time, reviews,
@@ -52,6 +69,10 @@ location, and FAQ content live in **`lib/site.config.ts`**. Editing or
 generating that file updates both the site and booking engine. Services and
 hours stay in config rather than a separate database.
 
+The tab icon is `app/icon.svg` (with `public/favicon.ico` for browsers that
+request `/favicon.ico`). Both carry this brand's letter and colors; replace
+them when you rename the brand.
+
 ## Layout
 
 ```
@@ -59,12 +80,15 @@ app.ts                       data model (Booking, BookedSlot, User) + policies
 lib/site.config.ts           ALL copy + brand + services + hours (edit this)
 lib/slots.ts                 pure slot math, shared by picker + server re-check
 lib/booking.ts               shared booking-row types
+lib/hours.ts                 weekly hours rows + directions link
+lib/demo.ts                  demo bookings + the dev-only gate
 lib/owner.ts                 owner-email gate (PYLON_OWNER_EMAIL)
 functions/createBooking.ts   public mutation: re-check + book (race-safe)
 functions/bookingsForOwner.ts  owner-only query: bookings + customer PII
 functions/{confirm,cancel}Booking.ts  owner-only mutations
-app/page.tsx                 the landing page (server-rendered)
-app/booking-widget.tsx       client island: live slot picker + booking form
+functions/seedDemo.ts        dev-only demo bookings (see Demo data)
+app/(marketing)/page.tsx     the landing page (server-rendered)
+app/(marketing)/booking-widget.tsx  client island: live slot picker + booking form
 app/login/page.tsx           owner sign-in
 app/dashboard/               owner dashboard (auth-gated, live)
 app/globals.css              Tailwind entrypoint (compiled by Pylon)