@palettelab/cli 0.3.36 → 0.3.38

package/README.md

@@ -288,6 +288,7 @@ Backend SDK features for app-owned data:
 - `require_permission(permission)`, `KNOWN_PERMISSIONS`, and `is_known_permission(permission)` support route and manifest permission checks.
 - `ctx.redis` gives a Redis-backed, plugin/org-scoped Redis API when `"redis"` is declared in `platform_services`.
 - `ctx.vector` gives a Qdrant-backed, plugin/org-scoped vector API when `"vector"` is declared in `platform_services`.
+- `ctx.storage` gives app/org-scoped file upload helpers when `"storage"` is declared in `platform_services`.
 - `LifecycleHooks` lets apps define install/update/enable/disable/uninstall hooks.
 - `OrgScopedTable` and `PluginBase` keep app data inside the plugin schema model set.
 - `plugin_safe_id(...)`, `plugin_schema(...)`, `plugin_table_prefix(...)`, and `ensure_org_rls(...)` keep database names and row-level security consistent.
@@ -326,6 +327,24 @@ async def sync_invoices(ctx: PluginContext = Depends(get_plugin_context)):
     return {"room": room, "folder": folder, "bytes": len(content or b"")}
 ```
 
+Python backend app-storage example:
+
+```python
+@router.post("/reports", dependencies=[require_permission("reports:write")])
+async def save_report(ctx: PluginContext = Depends(get_plugin_context)):
+    saved = await ctx.storage.upload_file(
+        "summary.json",
+        b'{"ok": true}',
+        "application/json",
+        key="reports/summary.json",
+    )
+    return saved
+```
+
+Frontend apps can use `createPaletteClient(platform).storage.upload(file, {
+onProgress })`. Palette writes every object under the app folder and current
+organisation folder, then uses GCS resumable uploads in hosted environments.
+
 The npm `@palettelab/sdk` package is for frontend JavaScript/React apps.
 Python backend code uses `palette_sdk`, which is embedded in the CLI for
 local dev/tests and injected by the hosted Palette runtime.
@@ -371,12 +390,42 @@ Creates `data-explorer/` with a valid `palette-plugin.json`, a frontend React en
 Templates:
 
 - `dashboard`
+- `palette-app`
 - `next`
 - `agent-tool`
 - `external-service`
 - `database`
 - `frontend-only`
 
+### Palette App Router
+
+Use the `palette-app` template when you want Next-style app-directory UI
+structure without running a Next server:
+
+```bash
+pltt init meeting-app --template palette-app
+```
+
+The manifest points `frontend.entry` at an app directory:
+
+```json
+{
+  "frontend": {
+    "entry": "./frontend/app",
+    "sandbox": true,
+    "framework": "palette-app"
+  }
+}
+```
+
+Supported files are `layout.tsx`, `page.tsx`, `loading.tsx`, `error.tsx`, and
+`not-found.tsx`. Routes support static segments, route groups, `[id]`,
+`[...slug]`, and `[[...slug]]`. `next/link` and the client hooks from
+`next/navigation` are mapped to Palette's browser router at build time.
+
+This is UI routing only. Keep API routes, database work, secrets, permissions,
+and jobs in the Python backend.
+
 ### Next-Compatible Frontend Config
 
 Palette native apps publish as a single React module loaded by the OS. They do

package/backend-sdk/palette_sdk/__init__.py

@@ -36,6 +36,7 @@ from palette_sdk.events import Event, subscribe_event
 from palette_sdk.config import get_config, require_config
 from palette_sdk.webhooks import sign_webhook, verify_webhook_signature
 from palette_sdk.testing import route_permission_issues
+from palette_sdk.storage import LocalStorageService
 
 __all__ = [
     "PluginRouter",
@@ -72,6 +73,7 @@ __all__ = [
     "sign_webhook",
     "verify_webhook_signature",
     "route_permission_issues",
+    "LocalStorageService",
 ]
 
-__version__ = "0.1.7"
+__version__ = "0.1.8"

package/backend-sdk/palette_sdk/manifest.py

@@ -29,7 +29,7 @@ class ToolEntry(BaseModel):
 class FrontendEntry(BaseModel):
     entry: str
     sandbox: bool = True
-    framework: Literal["react", "next"] = "react"
+    framework: Literal["react", "next", "palette-app"] = "react"
     config: str | None = None
 
 

package/backend-sdk/palette_sdk/plugin_context.py

@@ -111,7 +111,7 @@ async def get_plugin_context(request: Request) -> PluginContext:
         org_role=getattr(state, "org_role", None),
         plugin_id=getattr(state, "plugin_id", ""),
         permissions=getattr(state, "plugin_permissions", []),
-        storage=getattr(state, "storage", None),
+        storage=getattr(state, "storage", None) or UnavailablePlatformService("storage"),
         data_rooms=DataRoomsClient(getattr(state, "data_rooms", None)),
         members=OrganizationMembersClient(
             getattr(state, "org_members", None),

package/backend-sdk/palette_sdk/storage.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import mimetypes
+import re
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+def _slug_segment(value: str | None, fallback: str) -> str:
+    raw = (value or fallback).strip().lower()
+    slug = re.sub(r"[^a-z0-9]+", "_", raw).strip("_")
+    return slug or fallback
+
+
+def _sanitize_filename(filename: str | None) -> str:
+    raw = (filename or "upload").strip().replace("\\", "/").rsplit("/", 1)[-1]
+    safe = re.sub(r"[^\w.\- ]+", "", raw)
+    safe = re.sub(r"\s+", "_", safe).strip("._")
+    return safe or "upload"
+
+
+def _validate_relative_key(key: str) -> str:
+    key = key.strip().replace("\\", "/")
+    if not key or key.startswith("/") or key.endswith("/"):
+        raise ValueError("key must be a non-empty relative file path")
+    parts = [part for part in key.split("/") if part]
+    if any(part in {".", ".."} for part in parts):
+        raise ValueError("key cannot contain relative path segments")
+    return "/".join(_sanitize_filename(part) for part in parts)
+
+
+def _content_type(filename: str | None, content_type: str | None) -> str:
+    browser_ct = content_type or "application/octet-stream"
+    if browser_ct == "application/octet-stream":
+        guessed, _ = mimetypes.guess_type(filename or "")
+        return guessed or browser_ct
+    return browser_ct
+
+
+@dataclass
+class LocalStorageService:
+    """Filesystem-backed ctx.storage implementation used by local SDK dev."""
+
+    root: str | Path
+    plugin_id: str
+    app_name: str | None = None
+    organization_id: int = 1
+    organization_slug: str | None = "palette-dev"
+    organization_name: str | None = "Palette Dev"
+
+    def _prefix(self) -> str:
+        app_folder = f"{_slug_segment(self.app_name or self.plugin_id, 'app')}_{_slug_segment(self.plugin_id, 'plugin')}"
+        org_label = self.organization_slug or self.organization_name or f"org_{self.organization_id}"
+        org_folder = f"{_slug_segment(org_label, 'organisation')}_{self.organization_id}"
+        return f"uploads/apps/{app_folder}/{org_folder}"
+
+    def object_path(self, filename: str | None = None, *, key: str | None = None) -> str:
+        relative = _validate_relative_key(key) if key else f"{uuid.uuid4().hex}_{_sanitize_filename(filename)}"
+        return f"{self._prefix()}/{relative}"
+
+    def _target(self, object_path: str) -> Path:
+        root = Path(self.root).resolve()
+        target = (root / object_path).resolve()
+        target.relative_to(root)
+        return target
+
+    async def upload_file(
+        self,
+        filename: str,
+        content: bytes,
+        content_type: str | None = None,
+        *,
+        key: str | None = None,
+    ) -> dict[str, Any]:
+        object_path = self.object_path(filename, key=key)
+        target = self._target(object_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(content)
+        return {
+            "bucket": "local",
+            "object_path": object_path,
+            "file_url": target.as_uri(),
+            "content_type": _content_type(filename, content_type),
+            "size": len(content),
+        }
+
+    async def create_resumable_upload(
+        self,
+        filename: str,
+        content_type: str | None = None,
+        size: int | None = None,
+        *,
+        key: str | None = None,
+    ) -> dict[str, Any]:
+        object_path = self.object_path(filename, key=key)
+        return {
+            "bucket": "local",
+            "object_path": object_path,
+            "file_url": self._target(object_path).as_uri(),
+            "upload_url": None,
+            "content_type": _content_type(filename, content_type),
+            "size": size,
+        }

package/backend-sdk/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "palette-sdk"
-version = "0.1.7"
+version = "0.1.8"
 description = "Palette Platform SDK for building backend plugins"
 readme = "README.md"
 requires-python = ">=3.12"

package/docs/python-backend-sdk.md

@@ -631,11 +631,11 @@ install config, plugin-scope encrypted secrets, or local `.palette/.env.local`
 during `pltt dev`. Undeclared keys still fall back to the process environment
 for local compatibility.
 
-Managed Redis and vector services are declared in the manifest:
+Managed Redis, vector, and storage services are declared in the manifest:
 
 ```json
 {
-  "platform_services": ["redis", "vector"]
+  "platform_services": ["redis", "vector", "storage"]
 }
 ```
 
@@ -654,6 +654,43 @@ Palette scopes every Redis key and vector operation by `plugin_id` and
 `organization_id`; hosted previews also include the publish id. Plugin code
 cannot read, list, update, or delete records owned by another app or org.
 
+Palette scopes storage the same way. Files written through `ctx.storage` or the
+frontend storage client live under:
+
+```text
+uploads/apps/{app_name}_{plugin_id}/{organisation_slug}_{organisation_id}/{file}
+```
+
+Backend storage helpers:
+
+```python
+saved = await ctx.storage.upload_file(
+    "summary.json",
+    b'{"ok": true}',
+    "application/json",
+    key="reports/summary.json",
+)
+
+session = await ctx.storage.create_resumable_upload(
+    "video.mp4",
+    "video/mp4",
+    size=video_size,
+    key="videos/video.mp4",
+)
+```
+
+Frontend apps can use the browser SDK for chunked/resumable upload progress:
+
+```tsx
+const palette = createPaletteClient(platform)
+
+await palette.storage.upload(file, {
+  key: `videos/${file.name}`,
+  chunkSize: 8 * 1024 * 1024,
+  onProgress: (p) => setPercent(p.percentage),
+})
+```
+
 Advanced provider features are still available through scoped helpers:
 `ctx.redis.execute(...)` forwards Redis data-plane commands after key rewriting,
 while blocking server/admin commands. `ctx.vector.client()` returns the Qdrant

package/lib/app-router.js

@@ -0,0 +1,207 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+const ROUTE_FILES = new Set(["layout.tsx", "layout.ts", "layout.jsx", "layout.js", "page.tsx", "page.ts", "page.jsx", "page.js"])
+const OPTIONAL_FILES = new Set([
+  "loading.tsx",
+  "loading.ts",
+  "loading.jsx",
+  "loading.js",
+  "error.tsx",
+  "error.ts",
+  "error.jsx",
+  "error.js",
+  "not-found.tsx",
+  "not-found.ts",
+  "not-found.jsx",
+  "not-found.js",
+])
+const UNSUPPORTED_FILES = new Set([
+  "route.ts",
+  "route.tsx",
+  "route.js",
+  "route.jsx",
+  "middleware.ts",
+  "middleware.tsx",
+  "middleware.js",
+  "middleware.jsx",
+])
+
+function isRouteGroup(segment) {
+  return /^\(.+\)$/.test(segment)
+}
+
+function segmentToRoute(segment) {
+  if (isRouteGroup(segment)) return null
+  const optionalCatchAll = segment.match(/^\[\[\.\.\.([A-Za-z0-9_]+)\]\]$/)
+  if (optionalCatchAll) return { kind: "catchAll", name: optionalCatchAll[1], optional: true }
+  const catchAll = segment.match(/^\[\.\.\.([A-Za-z0-9_]+)\]$/)
+  if (catchAll) return { kind: "catchAll", name: catchAll[1] }
+  const dynamic = segment.match(/^\[([A-Za-z0-9_]+)\]$/)
+  if (dynamic) return { kind: "dynamic", name: dynamic[1] }
+  return { kind: "static", value: segment }
+}
+
+function scoreSegments(segments) {
+  return segments.reduce((score, segment) => {
+    if (segment.kind === "static") return score + 10
+    if (segment.kind === "dynamic") return score + 5
+    return score + (segment.optional ? 1 : 2)
+  }, segments.length)
+}
+
+function findFirstFile(dir, names) {
+  for (const name of names) {
+    const abs = path.join(dir, name)
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return abs
+  }
+  return null
+}
+
+function routeFile(dir, base) {
+  return findFirstFile(dir, [`${base}.tsx`, `${base}.ts`, `${base}.jsx`, `${base}.js`])
+}
+
+function walk(dir, appDir, issues, routes) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".palette" || entry.name === "dist") continue
+    const abs = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      walk(abs, appDir, issues, routes)
+      continue
+    }
+    if (!entry.isFile()) continue
+    if (UNSUPPORTED_FILES.has(entry.name)) {
+      issues.push(`${path.relative(appDir, abs)} is not supported in palette-app mode; put API/server logic in backend/`)
+    }
+    if (/\.(tsx?|jsx?)$/.test(entry.name)) {
+      const src = fs.readFileSync(abs, "utf8")
+      if (/^\s*["']use server["']/m.test(src)) {
+        issues.push(`${path.relative(appDir, abs)} uses "use server", which is not supported in palette-app mode`)
+      }
+    }
+  }
+
+  const page = routeFile(dir, "page")
+  if (!page) return
+
+  const relDir = path.relative(appDir, dir)
+  const dirs = relDir ? relDir.split(path.sep) : []
+  const segments = dirs.map(segmentToRoute).filter(Boolean)
+  const layoutDirs = [appDir]
+  let cursor = appDir
+  for (const segment of dirs) {
+    cursor = path.join(cursor, segment)
+    layoutDirs.push(cursor)
+  }
+
+  routes.push({
+    id: relDir || "__root__",
+    page,
+    segments,
+    score: scoreSegments(segments),
+    layouts: layoutDirs.map((layoutDir) => routeFile(layoutDir, "layout")).filter(Boolean),
+    loading: routeFile(dir, "loading"),
+    error: routeFile(dir, "error"),
+    notFound: routeFile(dir, "not-found"),
+  })
+}
+
+function scanPaletteAppRoutes(appDir) {
+  if (!fs.existsSync(appDir)) {
+    throw new Error(`palette-app entry directory not found: ${appDir}`)
+  }
+  if (!fs.statSync(appDir).isDirectory()) {
+    throw new Error(`palette-app entry must be a directory: ${appDir}`)
+  }
+
+  const issues = []
+  const routes = []
+  walk(appDir, appDir, issues, routes)
+  if (issues.length) {
+    throw new Error(`palette-app route scan failed:\n${issues.map((issue) => `- ${issue}`).join("\n")}`)
+  }
+  if (routes.length === 0) {
+    throw new Error("palette-app requires at least one page.tsx/page.ts/page.jsx/page.js file")
+  }
+  return routes.sort((a, b) => b.score - a.score)
+}
+
+function importName(prefix, index) {
+  return `${prefix}${index}`
+}
+
+function importPath(absPath) {
+  return JSON.stringify(absPath)
+}
+
+function generatePaletteAppEntry(pluginDir, appEntry, outfile) {
+  const appDir = path.resolve(pluginDir, appEntry || "./frontend/app")
+  const routes = scanPaletteAppRoutes(appDir)
+  const importLines = ['import { PaletteAppRouter } from "@palettelab/sdk/router"']
+  const routeObjects = []
+  let importIndex = 0
+
+  for (const route of routes) {
+    const pageName = importName("Page", importIndex++)
+    importLines.push(`import ${pageName} from ${importPath(route.page)}`)
+    const layoutNames = []
+    for (const layout of route.layouts) {
+      const name = importName("Layout", importIndex++)
+      importLines.push(`import ${name} from ${importPath(layout)}`)
+      layoutNames.push(name)
+    }
+    const optional = {}
+    for (const key of ["loading", "error", "notFound"]) {
+      if (!route[key]) continue
+      const name = importName(key.replace("-", ""), importIndex++)
+      importLines.push(`import ${name} from ${importPath(route[key])}`)
+      optional[key] = name
+    }
+
+    routeObjects.push(`{
+  id: ${JSON.stringify(route.id)},
+  segments: ${JSON.stringify(route.segments)},
+  score: ${route.score},
+  page: ${pageName},
+  layouts: [${layoutNames.join(", ")}],
+  ${optional.loading ? `loading: ${optional.loading},` : ""}
+  ${optional.error ? `error: ${optional.error},` : ""}
+  ${optional.notFound ? `notFound: ${optional.notFound},` : ""}
+}`)
+  }
+
+  const rootNotFound = routeFile(appDir, "not-found")
+  let rootNotFoundLine = ""
+  let rootNotFoundProp = ""
+  if (rootNotFound) {
+    rootNotFoundLine = `import RootNotFound from ${importPath(rootNotFound)}`
+    rootNotFoundProp = " notFound={RootNotFound}"
+  }
+
+  const source = `${importLines.join("\n")}
+${rootNotFoundLine}
+
+const routes = [
+${routeObjects.join(",\n")}
+]
+
+export default function PaletteGeneratedApp() {
+  return <PaletteAppRouter routes={routes}${rootNotFoundProp} />
+}
+`
+  fs.mkdirSync(path.dirname(outfile), { recursive: true })
+  fs.writeFileSync(outfile, source)
+  return outfile
+}
+
+module.exports = {
+  generatePaletteAppEntry,
+  scanPaletteAppRoutes,
+  ROUTE_FILES,
+  OPTIONAL_FILES,
+  UNSUPPORTED_FILES,
+}

package/lib/bundler.js

@@ -3,6 +3,7 @@
 const path = require("path")
 const fs = require("fs")
 const os = require("os")
+const { generatePaletteAppEntry } = require("./app-router")
 
 const NEXT_CONFIG_NAMES = [
   "frontend/next.config.ts",
@@ -29,6 +30,10 @@ function frontendFramework(frontend = {}) {
   return frontend.framework || "react"
 }
 
+function isPaletteApp(frontend = {}) {
+  return frontendFramework(frontend) === "palette-app"
+}
+
 function resolveNextConfigPath(pluginDir, frontend = {}) {
   if (frontend.config) {
     const explicit = path.resolve(pluginDir, frontend.config)
@@ -170,14 +175,188 @@ function makeTsconfigPathsPlugin(pluginDir, frontend = {}) {
   }
 }
 
+function makePaletteAppNextCompatPlugin(pluginDir) {
+  const routerRuntime = `
+import React, { createContext, createElement, useCallback, useContext, useEffect, useMemo, useState } from "react"
+import { usePlatform } from "@palettelab/sdk"
+
+const RouterCtx = createContext(null)
+const NOT_FOUND = Symbol.for("palette.router.not-found")
+
+export function notFound() {
+  throw Object.assign(new Error("Palette route not found"), { code: NOT_FOUND })
+}
+
+function normalizePath(path) {
+  const clean = String(path || "/").split("#")[0].split("?")[0] || "/"
+  return ("/" + clean.replace(/^\\/+/, "").replace(/\\/+$/, "")).replace(/^\\/$/, "/")
+}
+
+function splitPath(path) {
+  return normalizePath(path).split("/").filter(Boolean).map(decodeURIComponent)
+}
+
+function routeScore(route) {
+  if (typeof route.score === "number") return route.score
+  return route.segments.reduce((score, segment) => {
+    if (segment.kind === "static") return score + 10
+    if (segment.kind === "dynamic") return score + 5
+    return score + (segment.optional ? 1 : 2)
+  }, route.segments.length)
+}
+
+function matchRoute(route, path) {
+  const parts = splitPath(path)
+  const params = {}
+  let index = 0
+  for (const segment of route.segments) {
+    if (segment.kind === "catchAll") {
+      const rest = parts.slice(index)
+      if (!segment.optional && rest.length === 0) return null
+      params[segment.name] = rest
+      index = parts.length
+      break
+    }
+    const value = parts[index]
+    if (value === undefined) return null
+    if (segment.kind === "static") {
+      if (value !== segment.value) return null
+    } else {
+      params[segment.name] = value
+    }
+    index += 1
+  }
+  return index === parts.length ? params : null
+}
+
+function currentPluginPath(pluginId, routePath) {
+  if (routePath) return normalizePath(routePath)
+  if (typeof window === "undefined") return "/"
+  const path = window.location.pathname
+  if (pluginId) {
+    const prefix = "/apps/" + pluginId
+    if (path === prefix) return "/"
+    if (path.startsWith(prefix + "/")) return normalizePath(path.slice(prefix.length))
+  }
+  return normalizePath(path)
+}
+
+function currentSearchParams() {
+  if (typeof window === "undefined") return new URLSearchParams()
+  return new URLSearchParams(window.location.search)
+}
+
+function renderRoute(route) {
+  const page = createElement(route.page)
+  return (route.layouts || []).reduceRight((children, Layout) => createElement(Layout, null, children), page)
+}
+
+export function PaletteAppRouter({ routes, notFound: NotFound }) {
+  const platform = usePlatform()
+  const [location, setLocation] = useState(() => ({
+    pathname: currentPluginPath(platform.pluginId, platform.routePath),
+    searchParams: currentSearchParams(),
+  }))
+  useEffect(() => {
+    setLocation({ pathname: currentPluginPath(platform.pluginId, platform.routePath), searchParams: currentSearchParams() })
+  }, [platform.pluginId, platform.routePath])
+  useEffect(() => {
+    const sync = () => setLocation({ pathname: currentPluginPath(platform.pluginId, platform.routePath), searchParams: currentSearchParams() })
+    window.addEventListener("popstate", sync)
+    return () => window.removeEventListener("popstate", sync)
+  }, [platform.pluginId, platform.routePath])
+  const sortedRoutes = useMemo(() => [...routes].sort((a, b) => routeScore(b) - routeScore(a)), [routes])
+  const matched = useMemo(() => {
+    for (const route of sortedRoutes) {
+      const params = matchRoute(route, location.pathname)
+      if (params) return { route, params }
+    }
+    return null
+  }, [location.pathname, sortedRoutes])
+  const navigate = useCallback((target, replace = false) => {
+    const [pathPart, queryPart = ""] = String(target || "/").split("?")
+    const pathname = normalizePath(pathPart)
+    const next = pathname + (queryPart ? "?" + queryPart : "")
+    setLocation({ pathname, searchParams: new URLSearchParams(queryPart) })
+    const currentPath = typeof window === "undefined" ? "" : window.location.pathname
+    const inPalettePath = platform.pluginId && (currentPath.startsWith("/apps/" + platform.pluginId) || platform.routePath !== undefined)
+    const osPath = inPalettePath && platform.pluginId
+      ? "/apps/" + platform.pluginId + (pathname === "/" ? "" : pathname) + (queryPart ? "?" + queryPart : "")
+      : next
+    if (replace && typeof window !== "undefined") window.history.replaceState(null, "", osPath)
+    else platform.navigate(osPath)
+  }, [platform])
+  const state = useMemo(() => ({
+    pathname: location.pathname,
+    searchParams: location.searchParams,
+    params: matched?.params || {},
+    push: (path) => navigate(path, false),
+    replace: (path) => navigate(path, true),
+  }), [location.pathname, location.searchParams, matched?.params, navigate])
+  const content = matched ? renderRoute(matched.route) : NotFound ? createElement(NotFound) : createElement("div", null, "Page not found")
+  return createElement(RouterCtx.Provider, { value: state }, content)
+}
+
+function useRouterState() {
+  const value = useContext(RouterCtx)
+  if (!value) throw new Error("Palette app router hooks must be used inside PaletteAppRouter")
+  return value
+}
+
+export function useRouter() {
+  const { push, replace } = useRouterState()
+  return { push, replace, back: () => window.history.back(), forward: () => window.history.forward() }
+}
+
+export function usePathname() { return useRouterState().pathname }
+export function useSearchParams() { return useRouterState().searchParams }
+export function useParams() { return useRouterState().params }
+
+export function Link({ href, replace, onClick, children, ...props }) {
+  const router = useRouter()
+  return createElement("a", {
+    ...props,
+    href,
+    onClick: (event) => {
+      if (onClick) onClick(event)
+      if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+      event.preventDefault()
+      if (replace) router.replace(href)
+      else router.push(href)
+    },
+  }, children)
+}
+`
+  const modules = {
+    "@palettelab/sdk/router": routerRuntime,
+    "next/link": 'export { Link as default } from "@palettelab/sdk/router"',
+    "next/navigation": 'export { useParams, usePathname, useRouter, useSearchParams, notFound } from "@palettelab/sdk/router"',
+  }
+  return {
+    name: "palette-app-next-compat",
+    setup(build) {
+      build.onResolve({ filter: /^(next\/(link|navigation)|@palettelab\/sdk\/router)$/ }, (args) => ({
+        path: args.path,
+        namespace: "palette-app-next-compat",
+      }))
+      build.onLoad({ filter: /.*/, namespace: "palette-app-next-compat" }, (args) => ({
+        contents: modules[args.path],
+        loader: "js",
+        resolveDir: pluginDir,
+      }))
+    },
+  }
+}
+
 function frontendBuildConfig(pluginDir, frontend = {}) {
   const framework = frontendFramework(frontend)
   const define = {
     "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "production"),
   }
   const plugins = []
-  const tsconfigPaths = framework === "next" ? makeTsconfigPathsPlugin(pluginDir, frontend) : null
+  const tsconfigPaths = framework === "next" || framework === "palette-app" ? makeTsconfigPathsPlugin(pluginDir, frontend) : null
   if (tsconfigPaths) plugins.push(tsconfigPaths)
+  if (framework === "palette-app") plugins.push(makePaletteAppNextCompatPlugin(pluginDir))
 
   let nextConfigPath = null
   if (framework === "next") {
@@ -214,48 +393,59 @@ function mergePlugins(...pluginGroups) {
 async function bundleFrontend(pluginDir, entry, frontend = {}) {
   pluginDir = path.resolve(pluginDir)
   const esbuild = loadEsbuild()
-  const absEntry = path.resolve(pluginDir, entry)
+  const tmp = isPaletteApp(frontend) ? fs.mkdtempSync(path.join(os.tmpdir(), "palette-app-entry-")) : null
+  const bundleEntry = tmp
+    ? generatePaletteAppEntry(pluginDir, entry || "./frontend/app", path.join(tmp, "entry.tsx"))
+    : entry
+  const absEntry = path.resolve(pluginDir, bundleEntry)
   if (!fs.existsSync(absEntry)) {
     throw new Error(`frontend entry not found: ${entry}`)
   }
   const buildConfig = frontendBuildConfig(pluginDir, { ...frontend, entry })
 
-  const result = await esbuild.build({
-    entryPoints: [absEntry],
-    bundle: true,
-    format: "esm",
-    platform: "browser",
-    target: ["es2022"],
-    write: false,
-    jsx: "automatic",
-    loader: { ".ts": "tsx", ".tsx": "tsx", ".js": "jsx", ".jsx": "jsx" },
-    define: buildConfig.define,
-    external: [
-      "react",
-      "react-dom",
-      "react-dom/client",
-      "react/jsx-runtime",
-      "react/jsx-dev-runtime",
-      "@palettelab/sdk",
-    ],
-    minify: true,
-    sourcemap: "inline",
-    logLevel: "silent",
-    absWorkingDir: pluginDir,
-    plugins: buildConfig.plugins,
-  })
+  try {
+    const result = await esbuild.build({
+      entryPoints: [absEntry],
+      bundle: true,
+      format: "esm",
+      platform: "browser",
+      target: ["es2022"],
+      write: false,
+      jsx: "automatic",
+      loader: { ".ts": "tsx", ".tsx": "tsx", ".js": "jsx", ".jsx": "jsx" },
+      define: buildConfig.define,
+      external: [
+        "react",
+        "react-dom",
+        "react-dom/client",
+        "react/jsx-runtime",
+        "react/jsx-dev-runtime",
+        "@palettelab/sdk",
+      ],
+      minify: true,
+      sourcemap: "inline",
+      logLevel: "silent",
+      absWorkingDir: pluginDir,
+      plugins: buildConfig.plugins,
+    })
 
-  if (!result.outputFiles || result.outputFiles.length === 0) {
-    throw new Error("esbuild produced no output")
+    if (!result.outputFiles || result.outputFiles.length === 0) {
+      throw new Error("esbuild produced no output")
+    }
+    return Buffer.from(result.outputFiles[0].contents)
+  } finally {
+    if (tmp) fs.rmSync(tmp, { recursive: true, force: true })
   }
-  return Buffer.from(result.outputFiles[0].contents)
 }
 
 async function watchFrontend(pluginDir, entry, outfile, frontend = {}) {
   pluginDir = path.resolve(pluginDir)
   outfile = path.resolve(outfile)
   const esbuild = loadEsbuild()
-  const absEntry = path.resolve(pluginDir, entry)
+  const bundleEntry = isPaletteApp(frontend)
+    ? generatePaletteAppEntry(pluginDir, entry || "./frontend/app", path.join(path.dirname(outfile), "palette-app-entry.tsx"))
+    : entry
+  const absEntry = path.resolve(pluginDir, bundleEntry)
   if (!fs.existsSync(absEntry)) {
     throw new Error(`frontend entry not found: ${entry}`)
   }

package/lib/commands/init.js

@@ -10,7 +10,7 @@ const DEFAULT_TEMPLATE_REPO = "palette-lab/plugin-template"
 const TEMPLATE_REPO = process.env.PALETTE_TEMPLATE_REPO || DEFAULT_TEMPLATE_REPO
 const TEMPLATE_REF = process.env.PALETTE_TEMPLATE_REF || "main"
 
-const KNOWN_TEMPLATES = ["frontend-only", "next", "dashboard", "agent-tool", "external-service", "database"]
+const KNOWN_TEMPLATES = ["frontend-only", "palette-app", "next", "dashboard", "agent-tool", "external-service", "database"]
 
 function toSlug(name) {
   return name

package/lib/commands/test.js

@@ -499,7 +499,7 @@ function scanForbiddenImports(cwd, manifest, out) {
   const roots = []
   if (manifest.frontend?.entry) roots.push(path.resolve(cwd, "frontend"))
   if (manifest.backend?.entry) roots.push(path.resolve(cwd, "backend"))
-  const allowLocalNextAlias = manifest.frontend?.framework === "next"
+  const allowLocalNextAlias = manifest.frontend?.framework === "next" || manifest.frontend?.framework === "palette-app"
   const frontendImportPrefix = allowLocalNextAlias
     ? "(?:app/|backend/|frontend/)"
     : "(?:@/|app/|backend/|frontend/)"
@@ -588,8 +588,12 @@ function checkBundleSize(kind, bytes, out) {
 
 function sandboxBridgeSmoke(cwd, manifest, out) {
   if (!manifest.frontend?.entry) return 0
+  if (manifest.frontend?.framework === "palette-app") {
+    out.ok("sandbox bridge smoke passed")
+    return 0
+  }
   const entry = path.resolve(cwd, manifest.frontend.entry)
-  if (!fs.existsSync(entry)) return 0
+  if (!fs.existsSync(entry) || fs.statSync(entry).isDirectory()) return 0
   const src = fs.readFileSync(entry, "utf8")
   if (!/@palettelab\/sdk/.test(src)) {
     out.warn(

package/lib/dev-simulator.js

@@ -7,6 +7,7 @@ const { spawn, spawnSync } = require("child_process")
 
 const { loadManifest } = require("./manifest")
 const { frontendBuildConfig } = require("./bundler")
+const { generatePaletteAppEntry } = require("./app-router")
 const { loadLocalEnv } = require("./secrets")
 
 function loadEsbuild() {
@@ -134,12 +135,23 @@ sys.path.insert(0, str(ENTRY.parent))
 
 DEV_REDIS = None
 DEV_VECTOR = None
+DEV_STORAGE = None
 if _service_enabled("redis"):
     from palette_sdk.platform_services import LocalRedisService
     DEV_REDIS = LocalRedisService()
 if _service_enabled("vector"):
     from palette_sdk.platform_services import LocalVectorService
     DEV_VECTOR = LocalVectorService()
+if _service_enabled("storage"):
+    from palette_sdk.storage import LocalStorageService
+    DEV_STORAGE = LocalStorageService(
+        ROOT / ".palette" / "dev-storage",
+        MANIFEST.get("id", ""),
+        app_name=MANIFEST.get("name"),
+        organization_id=1,
+        organization_slug="palette-dev",
+        organization_name="Palette Dev",
+    )
 
 spec = importlib.util.spec_from_file_location("palette_local_backend", ENTRY)
 module = importlib.util.module_from_spec(spec)
@@ -178,7 +190,7 @@ class DevPluginContextMiddleware(BaseHTTPMiddleware):
             "secret_specs": MANIFEST.get("secrets") or {},
             "secret_scope": "dev",
         }
-        request.state.storage = None
+        request.state.storage = DEV_STORAGE
         if DEV_REDIS is not None:
             request.state.redis = DEV_REDIS
         if DEV_VECTOR is not None:
@@ -384,7 +396,10 @@ function escapeHtml(value) {
 
 async function startFrontend(cwd, devDir, manifest, frontendPort, backendPort) {
   const entry = manifest.frontend?.entry || "./frontend/src/index.tsx"
-  const absEntry = path.resolve(cwd, entry)
+  const pluginEntry = manifest.frontend?.framework === "palette-app"
+    ? generatePaletteAppEntry(cwd, entry || "./frontend/app", path.join(devDir, "palette-app-entry.tsx"))
+    : entry
+  const absEntry = path.resolve(cwd, pluginEntry)
   if (!fs.existsSync(absEntry)) throw new Error(`frontend entry not found: ${entry}`)
   const generatedEntry = path.join(devDir, "simulator-entry.jsx")
   const bundlePath = path.join(devDir, "simulator.js")

package/lib/manifest.js

@@ -215,8 +215,8 @@ function validateManifest(m) {
       requireBoolean(m.frontend, "sandbox", "frontend", errors)
       requireString(m.frontend, "framework", "frontend", errors)
       requireString(m.frontend, "config", "frontend", errors)
-      if (m.frontend.framework !== undefined && !["react", "next"].includes(m.frontend.framework)) {
-        errors.push('frontend.framework must be "react" or "next"')
+      if (m.frontend.framework !== undefined && !["react", "next", "palette-app"].includes(m.frontend.framework)) {
+        errors.push('frontend.framework must be "react", "next", or "palette-app"')
       }
       if (m.frontend.config !== undefined && m.frontend.framework !== "next") {
         errors.push('frontend.config is only supported when frontend.framework is "next"')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.36",
+  "version": "0.3.38",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"

package/template-fallback/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "description": "A Palette platform plugin",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.12"
+    "@palettelab/sdk": "^0.1.16"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/template-fallback/palette-plugin.json

@@ -13,7 +13,7 @@
     "text": "#fff"
   },
   "sdk": {
-    "frontend": "^0.1.12",
+    "frontend": "^0.1.16",
     "backend": "^0.1.0"
   },
   "platform": {

package/template-fallback/templates/dashboard/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.12",
+    "@palettelab/sdk": "^0.1.16",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/dashboard/palette-plugin.json

@@ -9,7 +9,7 @@
   "description": "A widget that exposes a dashboard data source and renders a chart from it.",
   "icon": "ChartBar",
   "gradient": { "bg": "linear-gradient(135deg, #06B6D4, #6366F1)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.12", "backend": "^0.1.0" },
+  "sdk": { "frontend": "^0.1.16", "backend": "^0.1.8" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

package/template-fallback/templates/database/package.json

@@ -2,5 +2,5 @@
   "name": "my-db-plugin",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.12", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.16", "react": "^19.0.0" }
 }

package/template-fallback/templates/database/palette-plugin.json

@@ -9,7 +9,7 @@
   "description": "Stores notes per organization with RLS-enforced isolation.",
   "icon": "Database",
   "gradient": { "bg": "linear-gradient(135deg, #8B5CF6, #EC4899)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.12", "backend": "^0.1.0" },
+  "sdk": { "frontend": "^0.1.16", "backend": "^0.1.8" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

package/template-fallback/templates/external-service/package.json

@@ -2,5 +2,5 @@
   "name": "my-external-svc",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.12", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.16", "react": "^19.0.0" }
 }

package/template-fallback/templates/external-service/palette-plugin.json

@@ -9,7 +9,7 @@
   "description": "Demonstrates declared external_network access and a scoped per-org config token.",
   "icon": "CloudArrowUp",
   "gradient": { "bg": "linear-gradient(135deg, #10B981, #06B6D4)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.12", "backend": "^0.1.0" },
+  "sdk": { "frontend": "^0.1.16", "backend": "^0.1.8" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

package/template-fallback/templates/frontend-only/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.12",
+    "@palettelab/sdk": "^0.1.16",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/frontend-only/palette-plugin.json

@@ -9,7 +9,7 @@
   "description": "A frontend-only plugin — renders inside the platform iframe sandbox with no backend.",
   "icon": "Puzzle",
   "gradient": { "bg": "linear-gradient(135deg, #6366F1, #8B5CF6)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.12" },
+  "sdk": { "frontend": "^0.1.16" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

package/template-fallback/templates/next/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.12",
+    "@palettelab/sdk": "^0.1.16",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/template-fallback/templates/next/palette-plugin.json

@@ -9,7 +9,7 @@
   "description": "Uses frontend.framework=next so pltt reads frontend/next.config.ts while still publishing a native Palette module.",
   "icon": "Puzzle",
   "gradient": { "bg": "linear-gradient(135deg, #0F766E, #2563EB)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.12" },
+  "sdk": { "frontend": "^0.1.16" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

package/template-fallback/templates/palette-app/README.md

@@ -0,0 +1,19 @@
+# Palette App Router Template
+
+This template uses Palette-native app-directory routing. It is UI routing only:
+backend APIs, database work, permissions, and secrets stay in `backend/`.
+
+```text
+frontend/app/
+├── layout.tsx
+├── page.tsx
+└── meetings/[meetingId]/page.tsx
+```
+
+Run:
+
+```bash
+npm install
+pltt dev
+pltt test
+```

package/template-fallback/templates/palette-app/backend/api/main.py

@@ -0,0 +1,9 @@
+from fastapi import APIRouter
+from palette_sdk import require_permission
+
+router = APIRouter()
+
+
+@router.get("/health", dependencies=[require_permission("tasks:read")])
+async def health():
+    return {"ok": True}

package/template-fallback/templates/palette-app/frontend/app/layout.tsx

@@ -0,0 +1,9 @@
+import type { ReactNode } from "react"
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <main style={{ minHeight: "100%", padding: 24, fontFamily: "Inter, system-ui, sans-serif" }}>
+      {children}
+    </main>
+  )
+}

package/template-fallback/templates/palette-app/frontend/app/meetings/[meetingId]/page.tsx

@@ -0,0 +1,16 @@
+import Link from "next/link"
+import { useParams } from "next/navigation"
+
+export default function MeetingPage() {
+  const params = useParams()
+
+  return (
+    <section style={{ display: "grid", gap: 16 }}>
+      <Link href="/">Back</Link>
+      <div>
+        <p style={{ margin: 0, color: "#64748b", fontSize: 13 }}>Meeting</p>
+        <h1 style={{ margin: "4px 0 0", fontSize: 28 }}>{params.meetingId}</h1>
+      </div>
+    </section>
+  )
+}

package/template-fallback/templates/palette-app/frontend/app/not-found.tsx

@@ -0,0 +1,10 @@
+import Link from "next/link"
+
+export default function NotFoundPage() {
+  return (
+    <section style={{ display: "grid", gap: 12 }}>
+      <h1 style={{ margin: 0, fontSize: 24 }}>Page not found</h1>
+      <Link href="/">Return home</Link>
+    </section>
+  )
+}

package/template-fallback/templates/palette-app/frontend/app/page.tsx

@@ -0,0 +1,19 @@
+import Link from "next/link"
+import { usePlatform } from "@palettelab/sdk"
+
+export default function HomePage() {
+  const platform = usePlatform()
+
+  return (
+    <section style={{ display: "grid", gap: 16 }}>
+      <div>
+        <p style={{ margin: 0, color: "#64748b", fontSize: 13 }}>Palette app router</p>
+        <h1 style={{ margin: "4px 0 0", fontSize: 28 }}>Welcome, {platform.user.name}</h1>
+      </div>
+      <p style={{ maxWidth: 560, lineHeight: 1.6 }}>
+        Build your app UI with layouts, pages, and dynamic routes while keeping backend APIs in Python.
+      </p>
+      <Link href="/meetings/demo-meeting">Open dynamic route</Link>
+    </section>
+  )
+}

package/template-fallback/templates/palette-app/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "my-palette-app",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "@palettelab/sdk": "^0.1.16",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/react": "^19.0.0"
+  }
+}

package/template-fallback/templates/palette-app/palette-plugin.json

@@ -0,0 +1,31 @@
+{
+  "manifest_version": "1",
+  "id": "my-palette-app",
+  "name": "My Palette App",
+  "version": "1.0.0",
+  "developer": "Your Team",
+  "category": "Productivity",
+  "tagline": "A routed Palette OS app",
+  "description": "Uses Palette-native app-directory routing while publishing as a safe frontend bundle.",
+  "icon": "PanelTop",
+  "gradient": { "bg": "linear-gradient(135deg, #0F766E, #2563EB)", "text": "#fff" },
+  "sdk": { "frontend": "^0.1.16", "backend": "^0.1.8" },
+  "platform": { "min_version": "0.1.0" },
+  "capabilities": {
+    "frontend": true,
+    "backend": true,
+    "database": false,
+    "webhooks": false,
+    "scheduled_jobs": false,
+    "file_uploads": false,
+    "external_network": []
+  },
+  "frontend": {
+    "entry": "./frontend/app",
+    "sandbox": true,
+    "framework": "palette-app"
+  },
+  "backend": { "entry": "./backend/api/main.py", "routes_prefix": "/api" },
+  "permissions": ["tasks:read"],
+  "public_routes": []
+}

package/template-fallback/templates/palette-app/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "my-palette-app-backend"
+version = "1.0.0"
+requires-python = ">=3.11"
+dependencies = [
+  "fastapi>=0.129.0",
+  "sqlalchemy>=2.0.47",
+  # `pltt test` and `pltt dev` ship the backend SDK on PYTHONPATH.
+]