@pantheon-systems/p1-next-sdk 0.6.0 → 0.8.0

package/bin/lib/cli.js

@@ -0,0 +1,171 @@
+/**
+ * Codemod orchestration.
+ *
+ * `migrate()` is pure-ish and testable (takes a dir, returns a result, throws
+ * BailError on unrecognized input). `runCLI()` wraps it with argv parsing and
+ * process exit codes for the bin entrypoint.
+ *
+ * All transforms run before any write, so a bail leaves the tree untouched —
+ * the app is never left half-migrated.
+ */
+
+import { join, relative } from "node:path";
+import { detectApp, assertSuiteVersions, isRouteSpecial } from "./detect.js";
+import { assertCleanTree } from "./git.js";
+import * as fsops from "./fs-ops.js";
+import * as msg from "./messages.js";
+import {
+  BailError,
+  rewriteEditorClient,
+  splitPageFile,
+  buildLayoutFile,
+} from "./transform.js";
+
+const show = (dir, target) => relative(dir, target) || target;
+
+/**
+ * The codemod's only irreversible act is removing the old catch-all, so when it
+ * holds anything else the bail has to be worth reading: name every file, and
+ * separate the ones that just need moving from the ones whose destination is a
+ * real decision.
+ */
+function extraFilesMessage({ catchAll, extras, p1Dir }, dir) {
+  const special = extras.filter(isRouteSpecial);
+  const plain = extras.filter((entry) => !isRouteSpecial(entry));
+  const group = show(dir, join(p1Dir, "(editor)"));
+  const lines = [
+    `${show(dir, catchAll)} contains files this codemod does not know how to move:`,
+  ];
+  if (plain.length > 0) {
+    lines.push(
+      "",
+      ...plain.map((entry) => `  ${entry}`),
+      `Move these into ${join(group, "[[...p1]]")}/ and add one ../ to each parent-relative import.`,
+    );
+  }
+  if (special.length > 0) {
+    lines.push(
+      "",
+      ...special.map((entry) => `  ${entry}`),
+      "These wrap the route segment. The editor now renders from " +
+        `${join(group, "layout.tsx")}, one level up, so they likely belong beside it in ${group}/.`,
+    );
+  }
+  lines.push(
+    "",
+    "Move them, then re-run — the page split, import depth, and layout are still handled for you.",
+  );
+  return lines.join("\n");
+}
+
+function partialMessage({ catchAll, p1Dir }, dir) {
+  return (
+    `Both ${show(dir, join(p1Dir, "(editor)"))} and ${show(dir, catchAll)} exist, so an ` +
+    "earlier run was interrupted before it removed the old route. Check which files you " +
+    `want to keep, delete ${show(dir, catchAll)}, then re-run.`
+  );
+}
+
+export async function migrate(opts = {}) {
+  const dir = opts.dir ?? process.cwd();
+  const force = opts.force ?? false;
+  const dryRun = opts.dryRun ?? false;
+
+  const app = detectApp(dir);
+  if (app.status === "already-migrated") {
+    msg.alreadyMigrated();
+    return { changed: false };
+  }
+  if (app.status === "not-found") {
+    throw new BailError(
+      `Could not find app/p1/[[...p1]]/page.tsx under ${dir}. Run this from your project root.`,
+    );
+  }
+  if (app.status === "partial") {
+    throw new BailError(partialMessage(app, dir));
+  }
+  if (app.status === "extra-files") {
+    throw new BailError(extraFilesMessage(app, dir));
+  }
+
+  // Runs on --dry-run too: a plan the installed suite cannot render is not a
+  // plan worth previewing.
+  if (assertSuiteVersions(dir).status === "unverified") msg.versionsUnverified();
+
+  if (!force && !dryRun && assertCleanTree(dir).status === "no-repo") msg.noGitRepo();
+
+  const { catchAll, p1Dir } = app;
+  const editorGroup = join(p1Dir, "(editor)");
+  const newCatchAll = join(editorGroup, "[[...p1]]");
+
+  // Transform everything up front — any bail happens before we touch disk.
+  const newEditorClient = rewriteEditorClient(fsops.read(join(catchAll, "editor-client.tsx")));
+  const { p1Pages, page } = splitPageFile(fsops.read(join(catchAll, "page.tsx")));
+  const layout = buildLayoutFile();
+
+  const writes = [
+    [join(newCatchAll, "editor-client.tsx"), newEditorClient],
+    [join(newCatchAll, "p1-pages.tsx"), p1Pages],
+    [join(newCatchAll, "page.tsx"), page],
+    [join(editorGroup, "layout.tsx"), layout],
+  ];
+
+  for (const [path] of writes) fsops.assertWithin(dir, path);
+  fsops.assertWithin(dir, catchAll);
+
+  if (dryRun) {
+    msg.dryRunPlan(writes.map(([path]) => path), catchAll);
+    return { changed: false, dryRun: true };
+  }
+
+  fsops.ensureDir(newCatchAll);
+  for (const [path, content] of writes) fsops.write(path, content);
+  fsops.removeDir(catchAll);
+
+  msg.success(writes.map(([path]) => path), catchAll);
+  return { changed: true };
+}
+
+/**
+ * Strict on purpose: a silently-ignored `--dryrun` would run the real migration,
+ * and a `--dir` given with a space would migrate the current directory instead
+ * of the one the user named.
+ */
+export function parseArgs(argv) {
+  const opts = { dir: process.cwd(), force: false, dryRun: false, help: false };
+  for (const arg of argv) {
+    if (arg === "--force" || arg === "-f") opts.force = true;
+    else if (arg === "--dry-run") opts.dryRun = true;
+    else if (arg === "--help" || arg === "-h") opts.help = true;
+    else if (arg.startsWith("--dir=")) opts.dir = arg.slice("--dir=".length);
+    else {
+      throw new BailError(
+        `Unrecognized argument: ${arg}. Run with --help to see the supported options.`,
+      );
+    }
+  }
+  return opts;
+}
+
+export async function runCLI(argv = process.argv.slice(2)) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    if (err instanceof BailError) msg.bail(err.message);
+    else msg.unexpected(err);
+    process.exitCode = 1;
+    return;
+  }
+  if (opts.help) {
+    msg.help();
+    return;
+  }
+  try {
+    await migrate(opts);
+  } catch (err) {
+    if (err instanceof BailError) msg.bail(err.message);
+    else msg.unexpected(err);
+    process.exitCode = 1;
+  }
+}

package/bin/lib/detect.js

@@ -0,0 +1,179 @@
+/**
+ * Classify a consumer project's editor route so the codemod knows whether to
+ * run, skip (already migrated), or bail (unrecognized), and verify the installed
+ * package suite is new enough for the shape this codemod writes.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { BailError } from "./transform.js";
+
+/** The only two files the codemod knows how to transform and carry across. */
+const MOVABLE = ["page.tsx", "editor-client.tsx"];
+
+/**
+ * App Router files whose behavior depends on where they sit. The editor moves
+ * up into `(editor)/layout.tsx`, so these stop wrapping it even when relocated
+ * faithfully — the destination is a judgment call the codemod should not make.
+ */
+const ROUTE_SPECIAL = new Set([
+  "layout",
+  "template",
+  "error",
+  "global-error",
+  "loading",
+  "not-found",
+  "default",
+  "route",
+]);
+
+export function isRouteSpecial(entry) {
+  return ROUTE_SPECIAL.has(entry.replace(/\.(tsx|ts|jsx|js)$/, ""));
+}
+
+function extraEntries(catchAll) {
+  return readdirSync(catchAll, { withFileTypes: true })
+    .filter((entry) => !MOVABLE.includes(entry.name))
+    .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
+    .sort();
+}
+
+export function detectApp(dir) {
+  const p1Dir = [join(dir, "app", "p1"), join(dir, "src", "app", "p1")].find((p) =>
+    existsSync(p),
+  );
+  if (!p1Dir) return { status: "not-found" };
+
+  const catchAll = join(p1Dir, "[[...p1]]");
+
+  if (existsSync(join(p1Dir, "(editor)"))) {
+    // Both trees present means a previous run died between the writes and the
+    // cleanup; calling that "already migrated" would strand the old route.
+    if (existsSync(catchAll)) return { status: "partial", p1Dir, catchAll };
+    return { status: "already-migrated", p1Dir };
+  }
+
+  if (
+    existsSync(join(catchAll, "page.tsx")) &&
+    existsSync(join(catchAll, "editor-client.tsx"))
+  ) {
+    const extras = extraEntries(catchAll);
+    if (extras.length > 0) return { status: "extra-files", p1Dir, catchAll, extras };
+    return { status: "legacy", p1Dir, catchAll };
+  }
+
+  return { status: "not-found" };
+}
+
+/**
+ * The release that moved the editor from `pages.Page` to `pages.Layout`. The
+ * codemod writes routes that call `Layout`, so anything older would be
+ * restructured to import an export that does not exist yet.
+ */
+export const MIN_SUITE_VERSION = "0.8.0";
+
+/**
+ * The lockstep-versioned packages a consumer app actually installs.
+ * `create-p1-starter-kit` is in the same `fixed` group but only ever scaffolds,
+ * so it is never present in the tree being migrated.
+ */
+const SUITE = [
+  "@pantheon-systems/p1-next-sdk",
+  "@pantheon-systems/puck-css",
+  "@pantheon-systems/css-client",
+];
+
+function readVersion(packageJsonPath) {
+  if (!existsSync(packageJsonPath)) return null;
+  try {
+    return JSON.parse(readFileSync(packageJsonPath, "utf-8")).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function manifestPath(...segments) {
+  return join(...segments, "package.json");
+}
+
+/** Numeric release triple, ignoring any prerelease tag. Null when unparseable. */
+function parseVersion(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(version));
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+
+function isOlderThan(version, floor) {
+  for (let i = 0; i < 3; i++) {
+    if (version[i] !== floor[i]) return version[i] < floor[i];
+  }
+  return false;
+}
+
+/**
+ * Verify the installed suite is consistent and new enough.
+ *
+ * Reads the installed tree rather than the consumer's declared ranges: a
+ * pre-1.0 caret is pinned to its minor, and an exact-pinned internal dep is
+ * satisfied by a nested private copy, so ranges cannot reveal either a stale
+ * install or a duplicated package. When nothing is resolvable we cannot verify
+ * anything — proceed rather than block, matching the clean-tree check.
+ *
+ * Only root-level packages are checked. Under pnpm's isolated node_modules just
+ * the app's direct dependencies are linked at the root, so a suite package
+ * missing from there is transitive, not broken — and a genuinely absent one
+ * fails loudly at build time anyway.
+ */
+export function assertSuiteVersions(dir) {
+  const modules = join(dir, "node_modules");
+  const resolved = SUITE.map((pkg) => ({
+    pkg,
+    version: readVersion(manifestPath(modules, pkg)),
+  })).filter((entry) => entry.version !== null);
+
+  if (resolved.length === 0) return { status: "unverified" };
+
+  const duplicates = [];
+  for (const { pkg: owner } of resolved) {
+    for (const { pkg: nested, version: root } of resolved) {
+      if (owner === nested) continue;
+      const version = readVersion(manifestPath(modules, owner, "node_modules", nested));
+      if (version !== null && version !== root) {
+        duplicates.push(`${nested}@${version} nested under ${owner}, and ${nested}@${root} at the root`);
+      }
+    }
+  }
+  if (duplicates.length > 0) {
+    throw new BailError(
+      `Your install has more than one copy of a P1 package: ${duplicates.join("; ")}. ` +
+        "Two copies mean two React contexts and the editor will misbehave at runtime. " +
+        "Upgrade every @pantheon-systems/* dependency in your package.json to the same " +
+        "version, reinstall, then re-run.",
+    );
+  }
+
+  const versions = [...new Set(resolved.map((entry) => entry.version))];
+  if (versions.length > 1) {
+    throw new BailError(
+      "Installed P1 packages are on different versions " +
+        `(${resolved.map((e) => `${e.pkg}@${e.version}`).join(", ")}). ` +
+        "They are released in lockstep and must match. Upgrade them together, then re-run.",
+    );
+  }
+
+  const [version] = versions;
+  const parsed = parseVersion(version);
+  if (parsed === null) return { status: "unverified" };
+
+  if (isOlderThan(parsed, parseVersion(MIN_SUITE_VERSION))) {
+    throw new BailError(
+      `Installed P1 packages are at ${version}, but the persistent (editor) layout ` +
+        `needs ${MIN_SUITE_VERSION} or newer. This codemod runs at the latest published ` +
+        "version because npx fetches it from the registry, so it can restructure routes " +
+        `your installed version cannot render. Note a "^${version}" range will not resolve ` +
+        `${MIN_SUITE_VERSION} — pre-1.0 carets are pinned to their minor — so upgrade ` +
+        "explicitly, reinstall, then re-run.",
+    );
+  }
+
+  return { status: "ok", version };
+}

package/bin/lib/fs-ops.js

@@ -0,0 +1,32 @@
+/**
+ * Filesystem helpers for the codemod, with a path-traversal guard so a write
+ * can never land outside the project being migrated.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { BailError } from "./transform.js";
+
+export function read(path) {
+  return readFileSync(path, "utf-8");
+}
+
+export function assertWithin(root, target) {
+  const r = resolve(root);
+  const t = resolve(target);
+  if (t !== r && !t.startsWith(r + sep)) {
+    throw new BailError(`Refusing to touch a path outside the project: ${target}`);
+  }
+}
+
+export function ensureDir(path) {
+  mkdirSync(path, { recursive: true });
+}
+
+export function write(path, content) {
+  writeFileSync(path, content);
+}
+
+export function removeDir(path) {
+  rmSync(path, { recursive: true, force: true });
+}

package/bin/lib/git.js

@@ -0,0 +1,60 @@
+/**
+ * A file-moving codemod needs a clean tree so the user can review its diff and
+ * roll back. Not being a git repo is a state we can report and proceed from;
+ * git being present but unable to answer is not — that is an unverified tree
+ * wearing the same mask, and the caller would delete files on the strength of
+ * a check that never ran.
+ */
+
+import { execFileSync } from "node:child_process";
+import { BailError } from "./transform.js";
+
+function runGit(args, dir) {
+  return execFileSync("git", args, {
+    cwd: dir,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function describeFailure(err) {
+  const stderr = typeof err?.stderr === "string" ? err.stderr.trim() : "";
+  return stderr || (err instanceof Error ? err.message : String(err));
+}
+
+function unverified(err) {
+  return new BailError(
+    `git could not verify the working tree (${describeFailure(err)}). ` +
+      "Fix that, or re-run with --force to migrate without a clean-tree check.",
+  );
+}
+
+/**
+ * @returns `{ status: "clean" }` when the target subtree has no pending changes,
+ * or `{ status: "no-repo" }` when there is no repository to check. Throws
+ * BailError when the tree is dirty or git could not answer.
+ */
+export function assertCleanTree(dir, run = runGit) {
+  try {
+    run(["rev-parse", "--git-dir"], dir);
+  } catch (err) {
+    if (/not a git repository/i.test(describeFailure(err))) return { status: "no-repo" };
+    throw unverified(err);
+  }
+
+  let out;
+  try {
+    // Scoped to the target: `git status` is repo-wide by default, so an
+    // unrelated dirty file elsewhere in a monorepo would block a clean subtree.
+    out = run(["status", "--porcelain", "--", "."], dir);
+  } catch (err) {
+    throw unverified(err);
+  }
+
+  if (out.trim()) {
+    throw new BailError(
+      "Working tree is not clean. Commit or stash your changes first, or re-run with --force.",
+    );
+  }
+  return { status: "clean" };
+}

package/bin/lib/messages.js

@@ -0,0 +1,65 @@
+/**
+ * All console output for the codemod, kept in one place. Plain text — no color
+ * dependency — so the SDK's runtime deps stay unchanged.
+ */
+
+import { MIN_SUITE_VERSION } from "./detect.js";
+
+const TAG = "[p1-migrate]";
+
+export function help() {
+  console.log(
+    [
+      "p1-migrate — migrate a P1 app to the persistent (editor) layout",
+      "",
+      "Usage: npx @pantheon-systems/p1-next-sdk p1-migrate [options]",
+      "",
+      "Options:",
+      "  --dir=<path>   Project directory to migrate (default: current directory)",
+      "  --dry-run      Show what would change without writing anything",
+      "  --force, -f    Skip the clean-git-tree check",
+      "  --help, -h     Show this help",
+    ].join("\n"),
+  );
+}
+
+export function alreadyMigrated() {
+  console.log(`${TAG} Already on the (editor) layout — nothing to do.`);
+}
+
+export function noGitRepo() {
+  console.log(
+    `${TAG} Not a git repository — skipping the clean-tree check. This rewrites and ` +
+      "removes files with no way to roll them back.",
+  );
+}
+
+export function versionsUnverified() {
+  console.log(
+    `${TAG} Could not read installed @pantheon-systems/* versions — skipping the version check.`,
+  );
+  console.log(
+    `${TAG} Make sure your dependencies are installed and on ${MIN_SUITE_VERSION} or newer.`,
+  );
+}
+
+export function dryRunPlan(writePaths, oldDir) {
+  console.log(`${TAG} Dry run — no files written. Planned changes:`);
+  for (const p of writePaths) console.log(`  write   ${p}`);
+  console.log(`  remove  ${oldDir}`);
+}
+
+export function success(writePaths, oldDir) {
+  console.log(`${TAG} Migrated to the persistent (editor) layout:`);
+  for (const p of writePaths) console.log(`  wrote   ${p}`);
+  console.log(`  removed ${oldDir}`);
+  console.log(`${TAG} Review the diff and commit when it looks right.`);
+}
+
+export function bail(message) {
+  console.error(`${TAG} Could not migrate automatically: ${message}`);
+}
+
+export function unexpected(err) {
+  console.error(`${TAG} Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+}

package/bin/lib/transform.js

@@ -0,0 +1,155 @@
+/**
+ * Pure string transforms for the p1-migrate codemod.
+ *
+ * No filesystem, no side effects — every function takes source in and returns
+ * source out (or throws BailError when the input isn't the shape we recognize).
+ * The moves and depth rule are mechanical; the two localized edits validate
+ * their target and bail rather than guess, so a diverged app is never left
+ * half-migrated.
+ */
+
+export class BailError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BailError";
+  }
+}
+
+/**
+ * Moving a file one directory deeper (into the `(editor)` group) adds a real
+ * on-disk segment the URL never sees, so every relative import that already
+ * points at a parent gains one more `../`. Sibling (`./`) and bare package
+ * specifiers are untouched.
+ */
+export function deepenRelativeImports(source) {
+  return source.replace(
+    /(\bfrom\s+|\bimport\s+|\bimport\(\s*|\brequire\(\s*)(['"])(\.\.\/)/g,
+    (_match, prefix, quote, dots) => `${prefix}${quote}../${dots}`,
+  );
+}
+
+/**
+ * Add `name` to the named-import list for `moduleSpecifier`. Idempotent when
+ * the name is already imported; bails when the module isn't imported at all.
+ */
+export function addNamedImport(source, moduleSpecifier, name, position = "append") {
+  const escaped = moduleSpecifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`(import\\s*\\{)([^}]*)(\\}\\s*from\\s*['"])${escaped}(['"])`);
+  const match = source.match(re);
+  if (!match) {
+    throw new BailError(
+      `Expected an import from "${moduleSpecifier}" to add "${name}" to; migrate this file by hand.`,
+    );
+  }
+  const names = match[2].split(",").map((s) => s.trim()).filter(Boolean);
+  if (names.includes(name)) return source;
+  const next = position === "prepend" ? [name, ...names] : [...names, name];
+  return source.replace(re, `$1 ${next.join(", ")} $3${moduleSpecifier}$4`);
+}
+
+const LEGACY_SIGNATURE =
+  /export function EditorClientWrapper\(\{\s*path\s*\}\s*:\s*\{\s*path\s*:\s*string\s*\}\s*\)\s*\{/;
+const MIGRATED_SIGNATURE = /export function EditorClientWrapper\(\s*\)/;
+
+/**
+ * Drop the `{ path }` prop from EditorClientWrapper and derive the path from
+ * the URL instead — matching how the persistent layout renders it with no props.
+ */
+export function rewriteWrapperSignature(source) {
+  if (LEGACY_SIGNATURE.test(source)) {
+    return source.replace(
+      LEGACY_SIGNATURE,
+      "export function EditorClientWrapper() {\n" +
+        "  // Rendered from the persistent (editor) layout, so this survives page\n" +
+        "  // switches; the edited page is derived from the URL instead of route params.\n" +
+        "  const pathname = usePathname();\n" +
+        "  const path = editorPagePathFromUrlPath(pathname);",
+    );
+  }
+  if (MIGRATED_SIGNATURE.test(source)) return source;
+  throw new BailError(
+    "EditorClientWrapper has an unrecognized signature; migrate this file by hand.",
+  );
+}
+
+/** Full editor-client transform: deepen imports, add the two named imports, rewrite the signature. */
+export function rewriteEditorClient(source) {
+  let out = deepenRelativeImports(source);
+  out = addNamedImport(out, "next/navigation", "usePathname", "prepend");
+  out = addNamedImport(out, "@pantheon-systems/p1-next-sdk", "editorPagePathFromUrlPath", "append");
+  out = rewriteWrapperSignature(out);
+  return out;
+}
+
+/** The thin page.tsx that re-exports from the shared p1-pages module. */
+export function buildNewPageFile() {
+  return (
+    'import { pages } from "./p1-pages";\n' +
+    "\n" +
+    "export default pages.Page;\n" +
+    "export const generateMetadata = pages.generateMetadata;\n" +
+    'export const dynamic = "force-dynamic";\n'
+  );
+}
+
+/** The `(editor)/layout.tsx` that renders the persistent editor. */
+export function buildLayoutFile() {
+  return (
+    'import "@puckeditor/core/puck.css";\n' +
+    'import { pages } from "./[[...p1]]/p1-pages";\n' +
+    "\n" +
+    "// The editor renders from this layout, NOT the page. The (editor) group is a\n" +
+    "// static segment, so this layout survives navigation between /p1/<pageA> and\n" +
+    "// /p1/<pageB> — a layout inside [[...p1]] would remount on every switch, since\n" +
+    "// Next keys segment cache nodes by param value.\n" +
+    "//\n" +
+    "// Scoping the layout to the (editor) group (instead of app/p1/layout.tsx) is\n" +
+    "// what keeps the editor off sibling routes: /p1/merge and future pages like\n" +
+    "// /p1/settings live outside the group and never render the editor. Add such\n" +
+    "// pages as siblings of (editor), not inside it.\n" +
+    "export default pages.Layout;\n"
+  );
+}
+
+/** The re-exports that belong to the route file, not the shared factory module. */
+const PAGE_LEVEL_EXPORTS = [
+  /^export default pages\.Page;\n/m,
+  /^export const generateMetadata = pages\.generateMetadata;\n/m,
+  /^export const dynamic = ["']force-dynamic["'];\n/m,
+];
+
+/**
+ * Split the old catch-all page.tsx into the shared factory module (p1-pages.tsx)
+ * and the thin re-export page.tsx. Bails when the file isn't the recognized
+ * createP1Pages editor page.
+ */
+export function splitPageFile(source) {
+  if (!source.includes("createP1Pages(") || !source.includes("pages.Page")) {
+    throw new BailError(
+      "page.tsx is not the recognized createP1Pages editor page; migrate it by hand.",
+    );
+  }
+  let p1Pages = deepenRelativeImports(source);
+  // The puck.css side-effect moves to layout.tsx.
+  p1Pages = p1Pages.replace(/^import ["']@puckeditor\/core\/puck\.css["'];\n/m, "");
+
+  // Export the factory result so both layout.tsx and page.tsx can consume it.
+  p1Pages = p1Pages.replace(/\bconst pages = createP1Pages\(/, "export const pages = createP1Pages(");
+  if (!/\bexport const pages = createP1Pages\(/.test(p1Pages)) {
+    throw new BailError(
+      "Could not find `const pages = createP1Pages(` to export from page.tsx; migrate this file by hand.",
+    );
+  }
+
+  // The page-level re-exports move to the thin page.tsx. Stripped individually
+  // so a reordered file does not leave dead exports behind in p1-pages.tsx.
+  for (const re of PAGE_LEVEL_EXPORTS) p1Pages = p1Pages.replace(re, "");
+  p1Pages = p1Pages.replace(/\n+$/, "\n");
+  if (/^export default pages\.Page;$/m.test(p1Pages)) {
+    throw new BailError(
+      "Could not remove the page-level exports from page.tsx; migrate this file by hand.",
+    );
+  }
+
+  return { p1Pages, page: buildNewPageFile() };
+}

package/bin/p1-migrate.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCLI } from "./lib/cli.js";
+
+runCLI();

package/dist/editor-paths.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Editor URL → page path mapping, shared by the server page handler and the
+ * client-side editor. Pure and client-safe: the editor renders from a
+ * persistent layout (so it survives route-param changes) and derives its page
+ * path from usePathname() with these helpers, which must agree with the
+ * server's parsing in pages-handler.
+ */
+export declare function parseEditorSegments(segments: string[]): string;
+export declare function editorPagePathFromUrlPath(pathname: string, basePath?: string): string;
+//# sourceMappingURL=editor-paths.d.ts.map

package/dist/editor-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-paths.d.ts","sourceRoot":"","sources":["../src/editor-paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAc9D;AAED,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAQ,GACf,MAAM,CAgBR"}

package/dist/editor-paths.js

@@ -0,0 +1,38 @@
+/**
+ * Editor URL → page path mapping, shared by the server page handler and the
+ * client-side editor. Pure and client-safe: the editor renders from a
+ * persistent layout (so it survives route-param changes) and derives its page
+ * path from usePathname() with these helpers, which must agree with the
+ * server's parsing in pages-handler.
+ */
+import { pagePathFromCatchAllSegments } from "@pantheon-systems/puck-css/routes";
+export function parseEditorSegments(segments) {
+    if (segments.length === 0)
+        return "/";
+    const command = segments[0];
+    // /p1/api/... is handled by the route handler, not the page
+    if (command === "api")
+        return "/";
+    // /p1/edit/... -> editor for the path
+    if (command === "edit") {
+        return pagePathFromCatchAllSegments(segments.slice(1));
+    }
+    // /p1/... (anything else) -> editor for that path
+    return pagePathFromCatchAllSegments(segments);
+}
+export function editorPagePathFromUrlPath(pathname, basePath = "/p1") {
+    if (pathname !== basePath && !pathname.startsWith(`${basePath}/`)) {
+        // Falling back silently would make the editor load and edit the root
+        // document while the URL points somewhere else entirely.
+        console.warn(`[p1-next-sdk] "${pathname}" is outside the editor base path "${basePath}"; ` +
+            `falling back to the root page. If the editor is not mounted at ${basePath}, ` +
+            `pass the correct basePath to editorPagePathFromUrlPath.`);
+        return "/";
+    }
+    const segments = pathname
+        .slice(basePath.length)
+        .split("/")
+        .filter(Boolean);
+    return parseEditorSegments(segments);
+}
+//# sourceMappingURL=editor-paths.js.map

package/dist/editor-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-paths.js","sourceRoot":"","sources":["../src/editor-paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AAEjF,MAAM,UAAU,mBAAmB,CAAC,QAAkB;IACpD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACtC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE5B,4DAA4D;IAC5D,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,GAAG,CAAC;IAElC,sCAAsC;IACtC,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,OAAO,4BAA4B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,kDAAkD;IAClD,OAAO,4BAA4B,CAAC,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,QAAgB,EAChB,QAAQ,GAAG,KAAK;IAEhB,IAAI,QAAQ,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC;QAClE,qEAAqE;QACrE,yDAAyD;QACzD,OAAO,CAAC,IAAI,CACV,kBAAkB,QAAQ,sCAAsC,QAAQ,KAAK;YAC3E,kEAAkE,QAAQ,IAAI;YAC9E,yDAAyD,CAC5D,CAAC;QACF,OAAO,GAAG,CAAC;IACb,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ;SACtB,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;SACtB,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,OAAO,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AACvC,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { P1NextRouterProvider } from "./P1NextRouterProvider";
+export { parseEditorSegments, editorPagePathFromUrlPath, } from "./editor-paths";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EACL,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { P1NextRouterProvider } from "./P1NextRouterProvider";
+export { parseEditorSegments, editorPagePathFromUrlPath, } from "./editor-paths";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EACL,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC"}

package/dist/pages-handler.d.ts

@@ -1,30 +1,60 @@
 /**
- * P1 Next SDK page handler — provides page components for `/p1/[...p1]`.
+ * P1 Next SDK page handler — provides page components for `/p1/[[...p1]]`.
+ *
+ * The editor renders from `Layout`, not `Page`: Next.js keys segment cache
+ * nodes by their param values, so everything inside `[[...p1]]` — page AND
+ * any layout placed there — remounts when the param changes, tearing down
+ * the whole editor (providers, auth, Puck and its canvas iframe) on every
+ * document switch. `Layout` must therefore be mounted at a static segment,
+ * which persists; the editor follows the URL client-side from there (see
+ * editor-paths.ts).
+ *
+ * Mount that layout in an `(editor)` route group rather than directly at
+ * `app/p1/layout.tsx`. A layout at `/p1` wraps EVERY route under it, so
+ * sibling routes with their own pages (e.g. /p1/merge, /p1/settings) would
+ * render the editor on top of themselves. Scoping the layout to the group
+ * means only the catch-all page gets the editor; siblings placed outside the
+ * group stay editor-free by construction. Route groups add no URL segment, so
+ * /p1 and its subpaths are unchanged.
  *
  * Usage:
- *   // app/p1/[...p1]/page.tsx
- *   import { createP1Pages } from "@pantheon-systems/p1-next-sdk";
- *   import config from "../../../puck.config";
- *   const pages = createP1Pages({ config });
+ *   // app/p1/(editor)/[[...p1]]/p1-pages.tsx (shared module)
+ *   import { createP1Pages } from "@pantheon-systems/p1-next-sdk/server";
+ *   export const pages = createP1Pages({ config, EditorClient });
+ *
+ *   // app/p1/(editor)/layout.tsx  <- static segment scoped to the group
+ *   export default pages.Layout;
+ *
+ *   // app/p1/(editor)/[[...p1]]/page.tsx
  *   export default pages.Page;
  *   export const generateMetadata = pages.generateMetadata;
  *   export const dynamic = "force-dynamic";
+ *
+ *   // app/p1/merge/page.tsx        <- sibling OUTSIDE the group, no editor
+ *   // app/p1/settings/page.tsx     <- future siblings: same, editor-free
+ *
+ * The editor must be mounted at `/p1`: the client derives the edited page
+ * from the URL via editorPagePathFromUrlPath, whose basePath defaults to
+ * "/p1". A different mount point needs that basePath passed through in the
+ * EditorClient implementation, or every URL falls back to the root page.
  */
 import type { Config } from "@puckeditor/core";
 import type { Metadata } from "next";
 import { type P1DataConfig } from "@pantheon-systems/puck-css/server";
 export type P1PagesConfig = P1DataConfig & {
     config: Config;
-    /** React component to render the editor. Receives only the page path; handles its own data loading and auth via P1App. */
-    EditorClient: React.ComponentType<{
-        path: string;
-    }>;
+    /**
+     * React component to render the editor. Rendered from the persistent
+     * layout with no props — it derives the page path from the URL (see
+     * editorPagePathFromUrlPath) and handles its own data loading and auth
+     * via P1App.
+     */
+    EditorClient: React.ComponentType;
 };
 export declare function createP1Pages(opts: P1PagesConfig): {
-    Page: ({ params, }: {
-        params: Promise<{
-            p1?: string[];
-        }>;
+    Page: () => null;
+    Layout: ({ children }: {
+        children: React.ReactNode;
     }) => Promise<import("react/jsx-runtime").JSX.Element>;
     generateMetadata: ({ params, }: {
         params: Promise<{

package/dist/pages-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pages-handler.d.ts","sourceRoot":"","sources":["../src/pages-handler.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAErC,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,mCAAmC,CAAC;AAE3C,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,0HAA0H;IAC1H,YAAY,EAAE,KAAK,CAAC,aAAa,CAAC;QAChC,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;CACJ,CAAC;AAmBF,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa;wBAiB5C;QACD,MAAM,EAAE,OAAO,CAAC;YAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;KACpC;oCAbE;QACD,MAAM,EAAE,OAAO,CAAC;YAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;KACpC,KAAG,OAAO,CAAC,QAAQ,CAAC;EAoBtB"}
+{"version":3,"file":"pages-handler.d.ts","sourceRoot":"","sources":["../src/pages-handler.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAErC,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,mCAAmC,CAAC;AAI3C,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG;IACzC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,YAAY,EAAE,KAAK,CAAC,aAAa,CAAC;CACnC,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa;;2BAyBX;QAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE;oCAX9D;QACD,MAAM,EAAE,OAAO,CAAC;YAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;KACpC,KAAG,OAAO,CAAC,QAAQ,CAAC;EAwCtB"}

package/dist/pages-handler.js

@@ -1,35 +1,43 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { pagePathFromCatchAllSegments, ensureInitialized, } from "@pantheon-systems/puck-css/server";
-function parsePath(path) {
-    if (path.length === 0)
-        return { pagePath: "/" };
-    const command = path[0];
-    // /p1/api/... is handled by the route handler, not the page
-    if (command === "api")
-        return { pagePath: "/" };
-    // /p1/edit/... -> editor for the path
-    if (command === "edit") {
-        const rest = path.slice(1);
-        return { pagePath: pagePathFromCatchAllSegments(rest) };
-    }
-    // /p1/... (anything else) -> editor for that path
-    return { pagePath: pagePathFromCatchAllSegments(path) };
-}
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { ensureInitialized, } from "@pantheon-systems/puck-css/server";
+import { parseEditorSegments } from "./editor-paths";
 export function createP1Pages(opts) {
     const { EditorClient } = opts;
     const initPromise = ensureInitialized(opts);
+    // A parent layout always renders before its child page within a request, so
+    // if the editor is mounted correctly Layout flips this before Page reads it.
+    // A legacy page-only app (no `(editor)/layout.tsx`) renders Page alone, and
+    // the flag is still false — the dev-only nudge below fires. Per-process,
+    // best-effort: it can't run in production and never affects output.
+    let layoutRendered = false;
+    let warnedMissingLayout = false;
     async function generateMetadata({ params, }) {
         await initPromise;
         const { p1 = [] } = await params;
-        const { pagePath } = parsePath(p1);
+        const pagePath = parseEditorSegments(p1);
         return { title: "P1 Editor: " + pagePath };
     }
-    async function Page({ params, }) {
+    // Persists across route-param changes — the editor lives here. Sets the flag
+    // synchronously (before any await) so Page can observe it in the same request.
+    async function Layout({ children }) {
+        layoutRendered = true;
         await initPromise;
-        const { p1 = [] } = await params;
-        const { pagePath } = parsePath(p1);
-        return _jsx(EditorClient, { path: pagePath });
+        return (_jsxs(_Fragment, { children: [_jsx(EditorClient, {}), children] }));
+    }
+    // Remounts per navigation; must stay empty so nothing is lost when it does.
+    function Page() {
+        if (process.env.NODE_ENV !== "production" &&
+            !layoutRendered &&
+            !warnedMissingLayout) {
+            warnedMissingLayout = true;
+            console.warn("[p1-next-sdk] The P1 editor now renders from pages.Layout, but this " +
+                "app rendered pages.Page without it — the editor will be empty. Mount " +
+                "it at app/p1/(editor)/layout.tsx, or run: " +
+                "npx @pantheon-systems/p1-next-sdk p1-migrate — see " +
+                "docs/MIGRATION-EDITOR-LAYOUT.md");
+        }
+        return null;
     }
-    return { Page, generateMetadata };
+    return { Page, Layout, generateMetadata };
 }
 //# sourceMappingURL=pages-handler.js.map

package/dist/pages-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"pages-handler.js","sourceRoot":"","sources":["../src/pages-handler.tsx"],"names":[],"mappings":";AAgBA,OAAO,EACL,4BAA4B,EAC5B,iBAAiB,GAElB,MAAM,mCAAmC,CAAC;AAU3C,SAAS,SAAS,CAAC,IAAc;IAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,4DAA4D;IAC5D,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;IAEhD,sCAAsC;IACtC,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3B,OAAO,EAAE,QAAQ,EAAE,4BAA4B,CAAC,IAAI,CAAC,EAAE,CAAC;IAC1D,CAAC;IAED,kDAAkD;IAClD,OAAO,EAAE,QAAQ,EAAE,4BAA4B,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAmB;IAC/C,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC9B,MAAM,WAAW,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAE5C,KAAK,UAAU,gBAAgB,CAAC,EAC9B,MAAM,GAGP;QACC,MAAM,WAAW,CAAC;QAClB,MAAM,EAAE,EAAE,GAAG,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC;QACjC,MAAM,EAAE,QAAQ,EAAE,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;QACnC,OAAO,EAAE,KAAK,EAAE,aAAa,GAAG,QAAQ,EAAE,CAAC;IAC7C,CAAC;IAED,KAAK,UAAU,IAAI,CAAC,EAClB,MAAM,GAGP;QACC,MAAM,WAAW,CAAC;QAClB,MAAM,EAAE,EAAE,GAAG,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC;QACjC,MAAM,EAAE,QAAQ,EAAE,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;QAEnC,OAAO,KAAC,YAAY,IAAC,IAAI,EAAE,QAAQ,GAAI,CAAC;IAC1C,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;AACpC,CAAC"}
+{"version":3,"file":"pages-handler.js","sourceRoot":"","sources":["../src/pages-handler.tsx"],"names":[],"mappings":";AA4CA,OAAO,EACL,iBAAiB,GAElB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAarD,MAAM,UAAU,aAAa,CAAC,IAAmB;IAC/C,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC9B,MAAM,WAAW,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAE5C,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,yEAAyE;IACzE,oEAAoE;IACpE,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,IAAI,mBAAmB,GAAG,KAAK,CAAC;IAEhC,KAAK,UAAU,gBAAgB,CAAC,EAC9B,MAAM,GAGP;QACC,MAAM,WAAW,CAAC;QAClB,MAAM,EAAE,EAAE,GAAG,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC;QACjC,MAAM,QAAQ,GAAG,mBAAmB,CAAC,EAAE,CAAC,CAAC;QACzC,OAAO,EAAE,KAAK,EAAE,aAAa,GAAG,QAAQ,EAAE,CAAC;IAC7C,CAAC;IAED,6EAA6E;IAC7E,+EAA+E;IAC/E,KAAK,UAAU,MAAM,CAAC,EAAE,QAAQ,EAAiC;QAC/D,cAAc,GAAG,IAAI,CAAC;QACtB,MAAM,WAAW,CAAC;QAClB,OAAO,CACL,8BACE,KAAC,YAAY,KAAG,EACf,QAAQ,IACR,CACJ,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,SAAS,IAAI;QACX,IACE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;YACrC,CAAC,cAAc;YACf,CAAC,mBAAmB,EACpB,CAAC;YACD,mBAAmB,GAAG,IAAI,CAAC;YAC3B,OAAO,CAAC,IAAI,CACV,sEAAsE;gBACpE,uEAAuE;gBACvE,4CAA4C;gBAC5C,qDAAqD;gBACrD,iCAAiC,CACpC,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;AAC5C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantheon-systems/p1-next-sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Next.js SDK for P1 editor integration",
   "publishConfig": {
     "access": "public",
@@ -15,6 +15,9 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "p1-migrate": "./bin/p1-migrate.js"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -26,20 +29,19 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "dependencies": {
     "server-only": "^0.0.1",
-    "@pantheon-systems/css-client": "0.6.0",
-    "@pantheon-systems/puck-css": "0.6.0"
+    "@pantheon-systems/css-client": "0.8.0",
+    "@pantheon-systems/puck-css": "0.8.0"
   },
   "peerDependencies": {
     "@puckeditor/core": ">=0.21.0",
     "next": ">=14.0.0",
     "react": ">=18.0.0",
-    "react-dom": ">=18.0.0",
-    "@pantheon-systems/css-client": "0.6.0",
-    "@pantheon-systems/puck-css": "0.6.0"
+    "react-dom": ">=18.0.0"
   },
   "devDependencies": {
     "@testing-library/dom": "^10.4.1",