Improve Docker dependency caching and isolate Python runtime

Reviewed-on: #45

.dockerignore

@@ -22,3 +22,18 @@ coverage
 
 # Local authoring assets are uploaded via APIs, never application build inputs.
 /content
+
+# Apply local metadata, secrets and generated-output exclusions at every depth.
+**/.git
+**/.worktrees
+**/.pnpm-store
+**/.turbo
+**/.nx
+**/coverage
+**/artifacts
+**/.pytest_cache
+**/*.egg-info
+**/*.tsbuildinfo
+**/.env
+**/.env.*
+!**/.env.example

.gitea/workflows/brand.yml

@@ -3,6 +3,7 @@ on:
   pull_request:
     branches: [main]
     paths:
+      - '.dockerignore'
       - 'packages/brand/**'
       - 'pnpm-workspace.yaml'
       - 'package.json'
@@ -11,6 +12,7 @@ on:
   push:
     branches: [main]
     paths:
+      - '.dockerignore'
       - 'packages/brand/**'
       - 'pnpm-workspace.yaml'
       - '.gitea/workflows/brand.yml'

.gitea/workflows/creative-workspace.yml

@@ -3,7 +3,11 @@ on:
   pull_request:
     branches: [main]
     paths:
+      - '.dockerignore'
+      - 'Dockerfile'
+      - 'pnpm-workspace.yaml'
       - 'apps/studio/**'
+      - 'packages/brand/**'
       - 'apps/waterfall-wiki/**'
       - '.gitea/workflows/**'
       - 'scripts/*studio*'
@@ -19,21 +23,27 @@ concurrency:
 jobs:
   verify-deployed-canvas:
     runs-on: ces-control
-    timeout-minutes: 10
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
-      - name: Verify canvas acceptance script against the designated deployed server
+      - name: Verify production acceptance against the designated deployed server
         run: |
+          node --check scripts/verify-studio-visual.cjs
           node --check apps/studio/scripts/infinite-canvas-smoke.cjs
-          wiki_image=$(docker inspect --format '{{.Config.Image}}' prompt-waterfall-wiki-1)
-          [[ "$wiki_image" =~ ^waterfall-wiki:[0-9a-f]{40}$ ]]
-          test_image="waterfall-wiki-tests:${wiki_image#waterfall-wiki:}"
-          docker image inspect "$test_image" >/dev/null
-          docker run --rm \
-            --mount "type=bind,src=$PWD,dst=/delivery,readonly" \
-            -e NODE_PATH=/repo/apps/waterfall-wiki/node_modules \
-            -e CHROMIUM_PATH=/usr/bin/chromium \
-            --entrypoint node "$test_image" /delivery/apps/studio/scripts/infinite-canvas-smoke.cjs
+          bash -n scripts/verify-studio-production.sh
+          bash scripts/verify-studio-production.sh
+      - name: Save server acceptance evidence
+        id: acceptance_evidence
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: studio-production-acceptance
+          path: artifacts/studio-acceptance/
+          if-no-files-found: ignore
+          retention-days: 7
+      - name: Remove temporary acceptance output after upload
+        if: always() && steps.acceptance_evidence.outcome == 'success'
+        run: rm -rf artifacts/studio-acceptance
   verify:
     runs-on: ces-control
     timeout-minutes: 60

.gitea/workflows/python.yml

@@ -1,15 +1,22 @@
 name: python CI and deployment
 on:
+  pull_request:
+    branches: [main]
+    paths:
+      - '.dockerignore'
+      - 'apps/python/**'
+      - 'scripts/deploy-python.sh'
+      - '.gitea/workflows/python.yml'
   push:
     branches: [main]
     paths:
+      - '.dockerignore'
       - 'apps/python/**'
       - 'scripts/deploy-python.sh'
       - '.gitea/workflows/python.yml'
 
 jobs:
   verify-and-deploy:
-    if: gitea.ref == 'refs/heads/main' && gitea.event_name == 'push'
     runs-on: ces-control
     timeout-minutes: 45
     steps:

.gitea/workflows/waterfall-wiki.yml

@@ -3,8 +3,10 @@ on:
   push:
     branches: [main]
     paths:
+      - '.dockerignore'
       - 'apps/waterfall-wiki/**'
       - 'apps/studio/**'
+      - 'packages/brand/**'
       - 'scripts/*studio*'
       - 'content/studio-examples/**'
       - 'content/studio-tools/layouts-api.md'

Dockerfile

@@ -12,12 +12,14 @@ LABEL io.entroia.wiki.build="true"
 RUN corepack enable && corepack prepare pnpm@11.25.0 --activate
 COPY apps/waterfall-wiki/pnpm-lock.yaml ./
 COPY pnpm-workspace.yaml /repo/pnpm-workspace.yaml
-COPY packages/brand/ /repo/packages/brand/
+COPY packages/brand/package.json /repo/packages/brand/package.json
 COPY apps/waterfall-wiki/package.json ./
 RUN pnpm --filter @prompt/waterfall-wiki install --frozen-lockfile --fetch-timeout=300000 --network-concurrency=8
 
 FROM dependencies AS build
 # .dockerignore excludes docs and operational notes without extra legacy COPY snapshots.
+# Brand source changes invalidate compilation, not dependency installation.
+COPY packages/brand/ /repo/packages/brand/
 COPY apps/waterfall-wiki/ .
 RUN pnpm typecheck && pnpm test && pnpm build && pnpm test:smoke
 

apps/python/Dockerfile

@@ -1,8 +1,22 @@
-FROM python:3.12-slim
+FROM python:3.12-slim AS base
 RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg fonts-noto-cjk && rm -rf /var/lib/apt/lists/*
+
+FROM base AS dependencies
+ENV PATH="/opt/venv/bin:$PATH"
 WORKDIR /app
+RUN python -m venv /opt/venv
+COPY apps/python/pyproject.toml ./
+# Read the pinned requirements from the package metadata before copying source.
+RUN python -c 'import subprocess, tomllib; p = tomllib.load(open("pyproject.toml", "rb")); subprocess.check_call(["python", "-m", "pip", "install", "--no-cache-dir", *p["build-system"]["requires"], *p["project"]["dependencies"]])'
+
+FROM dependencies AS build
 COPY apps/python/ .
-RUN pip install --no-cache-dir . && python -m unittest discover -s tests -v
+RUN pip install --no-cache-dir --no-deps --no-build-isolation . && python -m unittest discover -s tests -v
+
+FROM base AS runtime
+WORKDIR /app
+ENV PATH="/opt/venv/bin:$PATH"
+COPY --from=build /opt/venv /opt/venv
 RUN useradd --create-home exporter
 USER exporter
 ENTRYPOINT ["prompt-export"]

apps/studio/Dockerfile

@@ -3,9 +3,11 @@ WORKDIR /repo/apps/studio
 RUN corepack enable && corepack prepare pnpm@11.25.0 --activate
 COPY apps/studio/pnpm-lock.yaml ./
 COPY pnpm-workspace.yaml /repo/pnpm-workspace.yaml
-COPY packages/brand/ /repo/packages/brand/
+COPY packages/brand/package.json /repo/packages/brand/package.json
 COPY apps/studio/package.json ./
 RUN pnpm --filter @prompt/studio install --frozen-lockfile --fetch-timeout=300000 --network-concurrency=8
+# Brand source changes invalidate compilation, not dependency installation.
+COPY packages/brand/ /repo/packages/brand/
 COPY apps/studio/ .
 # Compare the two public parameter validators inside the isolated CI build.
 COPY apps/waterfall-wiki/src/lib/layout-parameters.ts /repo/apps/waterfall-wiki/src/lib/layout-parameters.ts

apps/waterfall-wiki/Dockerfile

@@ -10,12 +10,14 @@ WORKDIR /repo/apps/waterfall-wiki
 RUN corepack enable && corepack prepare pnpm@11.25.0 --activate
 COPY apps/waterfall-wiki/pnpm-lock.yaml ./
 COPY pnpm-workspace.yaml /repo/pnpm-workspace.yaml
-COPY packages/brand/ /repo/packages/brand/
+COPY packages/brand/package.json /repo/packages/brand/package.json
 COPY apps/waterfall-wiki/package.json ./
 RUN pnpm --filter @prompt/waterfall-wiki install --frozen-lockfile --fetch-timeout=300000 --network-concurrency=8
 
 FROM dependencies AS build
 # .dockerignore excludes docs and operational notes without extra legacy COPY snapshots.
+# Brand source changes invalidate compilation, not dependency installation.
+COPY packages/brand/ /repo/packages/brand/
 COPY apps/waterfall-wiki/ .
 RUN pnpm typecheck && pnpm test && pnpm build && pnpm test:smoke
 

apps/waterfall-wiki/src/components/LandingSketches.tsx

@@ -0,0 +1,25 @@
+type Pose = "idea" | "read" | "make" | "collect" | "dream";
+
+/** Original theme-aware line drawings, independent of the fixed brand mark. */
+export function CreatorSketch({ pose }: { pose: Pose }) {
+  return <svg viewBox="0 0 200 220" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+    <path d="M13 17 185 14l3 176-174 3ZM17 202q42-3 86 0m-85 8 62 1" strokeWidth="1.5" />
+    <path d="M42 188q3-46 31-60l42 1q28 16 42 59" fill="var(--selection)" />
+    <path d="M78 64q-20-3-15-20 5-15 21-11 11-15 29-6 20 7 11 31l-18-10-15 18Z" fill="currentColor" />
+    <path d="M79 63q-11 5-5 17l8 2q1 27 21 29 21-4 21-39l-3-15m-34 52-5 20m24-18 7 18m-17-58-2 13 8 2m-9 13q9 5 17-3m-23-23h1m24-1h1" />
+    {pose === "idea" && <><path d="m117 135 17-38 13-48 11 3-7 53-14 49M68 143l-5 27 37 15" fill="var(--background)" /><path d="m141 70-8-31 26-9 11 29Z" fill="var(--selection)" /><path d="m142 42 14-5m-11 14 13-5m-10 13 12-5M151 22V12m16 14 8-7m-41 12-9-4" /></>}
+    {pose === "read" && <><path d="m49 132 49 16 46-20-4 58-41 15-46-15Z" fill="var(--background)" /><path d="m98 148 1 53m-35-54 23 8m-22 3 20 7m-19 3 16 6m28-16 20-8m-20 19 18-7m-18 17 15-6" /><path d="m50 162 12-5q8 1 5 8l-14 13m89-17-12-4q-9 0-6 7l15 12" fill="var(--background)" /></>}
+    {pose === "make" && <><path d="m99 143 65-7 15 51-68 5Z" fill="var(--background)" /><path d="m101 150-22 3-8 19 32 5m-39-6 16 7 29-2m21-12h13m-28 29H37" /><path d="m151 46 5-14 8 12 15 2-11 9 1 15-13-8-13 5 4-13-10-10Z" fill="var(--selection)" /></>}
+    {pose === "collect" && <><path d="m60 156 15-18 53 7-5 40-62-5Z" fill="var(--background)" /><path d="m76 138 8-11 19 3 7 13m-12 9a12 12 0 1 0 1 24 12 12 0 0 0-1-24m-36 10-11-5-8 8 15 15m64-21 15 9-13 11" /><path d="m143 68 25-7 7 31-25 7Zm7 14 6-6 10 9m-8-14h1" stroke="var(--primary)" /></>}
+    {pose === "dream" && <><path d="m82 136 16 30 26-6 12-36m-18 38 18 11 11-35-7-20q-4-7-8-3l-2 14-6-7m-46 26-9 25 28 14 37-13" fill="var(--background)" /><path d="m142 32 29-10-13 25-4-12-12-3 12 3 17-13m-36 25q-21 4-15 17t25 2" stroke="var(--primary)" /></>}
+  </svg>;
+}
+
+export function IdeaSketch({ kind }: { kind: "collect" | "connect" | "read" | "make" }) {
+  return <svg viewBox="0 0 140 110" fill="none" stroke="currentColor" strokeWidth="2.1" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+    {kind === "collect" && <><path d="m43 25 49-5 7 64-53 6Z" fill="var(--selection)" /><path d="m54 39 25-2m-24 14 30-3m-28 14 21-2m20-23 18-20 7 7-20 21-9 3ZM34 18l-6-8m19 3-1-10m61 62 8 3m-81 2-10 2" /></>}
+    {kind === "connect" && <><path d="M42 37q27-31 50-1m-48 8q27-17 47-1M45 62q23 28 46 2" /><path d="m18 32 29-3 3 34-31 2Zm72-8 32 4-3 33-30-3ZM52 73l32-1 2 25-32 2Z" fill="var(--selection)" /><path d="m26 43 14-1m-13 9 10-1m62-13 13 2m-13 7 11 1M62 83h13m-12 7h9" /></>}
+    {kind === "read" && <><path d="M20 30q25-8 49 7 24-17 51-10l-3 56q-24-5-48 10-22-13-47-7Z" fill="var(--selection)" /><path d="m69 37 0 56M32 42q13-1 25 5m-23 8 21 5m-21 8 20 4m27-27 24-6m-23 19 21-6m-20 18 18-4m-35-44-2-11m17 10 6-10" /></>}
+    {kind === "make" && <><path d="m24 29 85-3 5 63-86 4ZM31 41h71M45 34h1m-10 0h1m20-1h1m-18 21 21-2 1 26-22 1Zm31 0 27-1m-26 12 20-1m-19 13 24-1" /><path d="m103 14 7-11 4 12 13 2-10 8 2 11-10-6-10 7 2-12-10-7Z" fill="var(--selection)" /></>}
+  </svg>;
+}

apps/waterfall-wiki/src/pages/index.tsx

@@ -1,12 +1,22 @@
 import { ThemeToggle } from "../components/ThemeToggle";
 import { Brand } from "../components/Brand";
 import Head from 'next/head';
-import {ArrowUpRight, MousePointer2, Plus, Type, Image, Sparkles, Workflow, Layers, ArrowRight} from 'lucide-react';
+import {ArrowUpRight, Workflow, Layers, ArrowRight} from 'lucide-react';
+import {CreatorSketch, IdeaSketch} from "@/components/LandingSketches";
 import s from '@/styles/landing.module.css';
 export default function Home(){return <main className={s.page}>
-<Head><title>啡跃 啡跃 Endoleap · 让灵感，有形。</title><meta name="description" content="连接你的 coding agent，在图形编辑器与无限画布中，把想法组织成作品。"/></Head>
-<nav className={s.nav}><a className={s.logo} href="/"><Brand/></a><div><a href="#tools">创作工具</a><a href="/documents">知识与教程</a><a href="#workflow">工作方式</a></div><ThemeToggle/><a href="/account?next=/workspace">登录</a><a className={s.dark} href="/account?next=/workspace">进入工作台 <ArrowUpRight size={15}/></a></nav>
-<section className={s.hero}><p className={s.eyebrow}>A SPACE FOR HUMAN IDEAS & AGENTS</p><h1>想法不该停在对话里。<br/><span>让灵感，有形。</span></h1><p className={s.intro}>从一闪而过的念头，到值得分享的作品。<br/>连接你的 coding agent，在一张画布上，把创作继续下去。</p><div className={s.actions}><a className={s.dark} href="/account?next=/workspace">开始创作 <ArrowRight size={17}/></a><a href="#tools">探索你的创作空间 ↓</a></div><div className={s.product}><div className={s.productBar}><Brand compact/><span>日常的另一种可能 / 创意探索</span><span>本机草稿</span></div><div className={s.demo}><aside>工作空间<hr/>图层与素材<p>◈ 创意简报</p><p>▧ 视觉探索</p><p>✳ 镜头构思</p><small>把线索连接起来</small></aside><div className={s.demoWorld}><svg viewBox="0 0 800 330" preserveAspectRatio="none"><path d="M190 170 C300 170 260 120 360 120 S520 240 620 240"/></svg><article className={s.note}><small>01 / THE IDEA</small><h3>把日常，<br/>拍成一场电影。</h3><p>自然光、细腻颗粒，<br/>让每一帧都有呼吸感。</p></article><article className={s.art}><small>02 / VISUAL STUDY</small><div className={s.orbit}/><h3>光的形状</h3><span>LIGHT / SPACE / EMOTION</span></article><article className={s.prompt}><Sparkles size={17}/><small>03 / PROMPT</small><h3>留住清晨的光。</h3><p>窗边的植物，安静的房间。<br/>35mm 胶片，缓慢推进。</p></article><div className={s.dock}><MousePointer2/><Plus/><Type/><Image/><Sparkles/></div></div></div></div><p className={s.caption}>一个创作场景示意。你的想法、素材与工具，在这里相遇。</p></section>
+<Head><title>啡跃 Endoleap · 让灵感，有形。</title><meta name="description" content="收藏灵感、连接知识，与熟悉的 Agent 一起，把想法变成作品。探索图形编辑器、无限画布与知识文档。"/></Head>
+<nav className={s.nav} aria-label="主导航"><a className={s.logo} href="/"><Brand/></a><div><a href="#tools">创作工具</a><a href="/documents">知识与教程</a><a href="#workflow">工作方式</a></div><ThemeToggle/><a href="/account?next=/workspace">登录</a><a className={s.dark} href="/account?next=/workspace">进入工作台 <ArrowUpRight size={15}/></a></nav>
+<section className={s.hero}><p className={s.eyebrow}>A SPACE FOR HUMAN IDEAS & AGENTS</p><h1>想法不该停在对话里。<br/><span>让灵感，有形。</span></h1><p className={s.intro}>从一闪而过的念头，到值得分享的作品。<br/>连接你的 coding agent，在一张画布上，把创作继续下去。</p><div className={s.actions}><a className={s.dark} href="/account?next=/workspace">开始创作 <ArrowRight size={17}/></a><a href="#tools">探索你的创作空间 ↓</a></div><div className={s.peopleStrip}><span className={s.stripNote}>每一种好奇，都有自己的起点。</span>{([
+ ['collect','收藏生活的切片'],['read','遇见新的工作方法'],['idea','记下突然出现的灵感'],['dream','给想法一点自由'],['make','做一件属于你的作品']
+] as const).map(([pose,label])=><figure key={pose}><CreatorSketch pose={pose}/><figcaption>{label}</figcaption></figure>)}<span className={s.stripSpark} aria-hidden="true">✳</span></div></section>
+<section className={s.possibilities} id="possibilities" aria-labelledby="possibilities-title"><p className={s.eyebrow}>MAKE ROOM FOR WHAT COMES NEXT</p><h2 id="possibilities-title">给好奇心一点空间，<br/>让下一步<em>自然发生。</em></h2><div className={s.featureGrid}>{([
+ ['collect','留住一闪而过','一句念头、一张参考图、一个还没想好的方向。先留下，再慢慢展开。'],
+ ['connect','让线索相遇','把笔记、图片和提示词放上画布，用连接看见它们之间的新可能。'],
+ ['read','找到有用的方法','阅读可独立使用的知识文档，需要更多背景时，沿链接继续探索。'],
+ ['make','把创作继续下去','用熟悉的 coding agent 探索，再亲手调整细节，让想法成为自己的作品。']
+] as const).map(([kind,title,copy])=><article key={kind}><IdeaSketch kind={kind}/><h3>{title}</h3><p>{copy}</p></article>)}</div></section>
 <section className={s.tools} id="tools"><p className={s.eyebrow}>TWO TOOLS. ONE CREATIVE FLOW.</p><h2>给不同的想法，<br/>恰好的空间。</h2><div className={s.toolGrid}><a href="/graphic"><Layers/><span>01 / GRAPHIC</span><h3>把灵感排成作品。</h3><p>文字、图形与图片自由编排。精确调整图层和位置，把设计导出为 SVG。</p><div className={s.poster}><span>MAKE<br/>ROOM<br/><i>for ideas.</i></span><b>✳</b></div><strong>打开图形编辑器 <ArrowUpRight size={17}/></strong></a><a href="/infinite_canvas"><Workflow/><span>02 / INFINITE CANVAS</span><h3>让思路，自由生长。</h3><p>把笔记、参考图与提示词连成线索。在无限画布上平移、缩放，整理下一次创作。</p><div className={s.miniCanvas}><b>一个念头</b><i>⟶</i><b>一张参考</b><i>⟶</i><b>新的可能</b></div><strong>打开无限画布 <ArrowUpRight size={17}/></strong></a></div></section>
+<section className={s.reading} aria-labelledby="reading-title"><div><p className={s.eyebrow}>GOOD IDEAS DESERVE GOOD COMPANY</p><h2 id="reading-title">不必每一次，<br/>都从空白开始。</h2><p>把有用的工作方法，留给下一次的自己。<br/>一篇文档讲清一件事，需要时再沿着链接走远一点。</p><a href="/documents">去知识空间逛逛 <ArrowUpRight size={16}/></a></div><div className={s.readingArt} aria-hidden="true"><span>读到这里，<br/><em>想到了什么？</em></span><CreatorSketch pose="read"/><small>READ. CONNECT. MAKE.</small><svg viewBox="0 0 440 380"><path d="M35 105q-20-55 35-64m-15 0 17-2-8 17M348 267q46 33 32 68m-14-13 14 15 14-13"/></svg></div></section>
 <section className={s.workflow} id="workflow"><div><p className={s.eyebrow}>YOUR AGENT. YOUR WORKFLOW.</p><h2>用熟悉的 Agent，<br/>继续你的创作。</h2><p>通过项目已有的 API 与文档，让 coding agent 理解模板和创作内容。画布负责呈现，你来决定下一步。</p><a href="/studio/api">查看 Agent 接入文档 <ArrowUpRight size={16}/></a></div><ol><li><b>01</b><div><h3>找到起点</h3><p>从空白设计、素材或一段灵感出发。</p></div></li><li><b>02</b><div><h3>连接工作方式</h3><p>将接入文档交给你的 coding agent。</p></div></li><li><b>03</b><div><h3>亲手打磨，保存作品</h3><p>在编辑器中调整细节，导出并保留备份。</p></div></li></ol></section>
-<section className={s.end}><span><Brand compact/></span><h2>下一件作品，<br/>从这里开始。</h2><a className={s.dark} href="/account?next=/workspace">进入你的工作台 <ArrowRight size={17}/></a></section><footer className={s.footer}><a className={s.logo} href="/"><Brand/></a><span>给想法留白，给创作空间。</span><a href="/documents">知识与教程 ↗</a></footer></main>}
+<section className={s.end}><div className={s.endWall} aria-hidden="true">{(['collect','read','connect','make'] as const).map(kind=><div key={kind}><IdeaSketch kind={kind}/><i/><i/><i/></div>)}</div><div className={s.endContent}><p className={s.eyebrow}>YOUR NEXT IDEA STARTS HERE</p><h2>给下一个念头，<br/><em>留一个起点。</em></h2><p>不用想好全部。带着一点好奇，先开始。</p><a className={s.dark} href="/account?next=/workspace">进入你的工作台 <ArrowRight size={17}/></a><a className={s.endSecondary} href="/documents">或先读一篇有用的文档 ↗</a></div></section><footer className={s.footer}><a className={s.logo} href="/"><Brand/></a><span>给想法留白，给创作空间。</span><a href="/documents">知识与教程 ↗</a></footer></main>}

apps/waterfall-wiki/tests/brand-navigation.mjs

@@ -51,9 +51,11 @@ export async function visitBrowserDocument(page, url, reload = false) {
         const remaining = timeout - (Date.now() - started);
         if (remaining <= 0) throw new Error('Document hydration budget exhausted: ' + url);
         try {
+          // Responsive layouts may hide the toggle. Its mounted ready marker
+          // proves hydration; each caller still checks the controls it needs.
           // A cancelled script may be a preload duplicate. Hydration is the
           // authority; recover only when cancellation actually blocks startup.
-          await page.locator('button[data-theme-ready="true"]').first().waitFor({timeout: failures.length ? Math.min(5000, remaining) : remaining});
+          await page.locator('button[data-theme-ready="true"]').first().waitFor({state: 'attached', timeout: failures.length ? Math.min(5000, remaining) : remaining});
         } catch (error) {
           if (failures.length) throw new Error('Document bootstrap script request failed: ' + failures.join('; '), {cause: error});
           throw error;

apps/waterfall-wiki/tests/brand-navigation.test.mjs

@@ -49,7 +49,7 @@ test('recovery cannot extend the total navigation budget', async () => {
   assert.equal(calls, 1);
 });
 
-function browserFixture(failBootstrap = false, failHydration = false, blockedOnce = false) {
+function browserFixture(failBootstrap = false, failHydration = false, blockedOnce = false, readyVisible = true) {
   const listeners = new Map(), calls = [];
   const page = {
     on(event, fn) { if (!listeners.has(event)) listeners.set(event, new Set()); listeners.get(event).add(fn); },
@@ -61,7 +61,7 @@ function browserFixture(failBootstrap = false, failHydration = false, blockedOnc
       if (failBootstrap && calls.length === 1) for (const fn of listeners.get('requestfailed') || []) fn(request);
       return response(200);
     },
-    locator() { return {first: () => ({waitFor: async () => { calls.push('hydrated'); if (failHydration || (blockedOnce && calls.length === 2)) throw Error('Hydration timeout'); }})}; },
+    locator() { return {first: () => ({waitFor: async options => { calls.push('hydrated'); if (!readyVisible && options.state !== 'attached') throw Error('Ready marker is hidden by responsive CSS'); if (failHydration || (blockedOnce && calls.length === 2)) throw Error('Hydration timeout'); }})}; },
   };
   return {page, calls, listeners};
 }
@@ -87,3 +87,9 @@ test('cancelled script does not reject an already hydrated document', async () =
   await visitBrowserDocument(page, '/account');
   assert.deepEqual(calls, ['domcontentloaded', 'hydrated']);
 });
+
+test('hydrated pages are ready even when responsive CSS hides the marker', async () => {
+  const {page, calls} = browserFixture(false, false, false, false);
+  await visitBrowserDocument(page, '/graphic');
+  assert.deepEqual(calls, ['domcontentloaded', 'hydrated']);
+});

apps/waterfall-wiki/tests/brand-ui-integration.ts

@@ -62,6 +62,14 @@ export async function verifyBrandUI(base: string) {
     await page.setViewportSize({ width: 390, height: 844 });
     assert.equal(await page.locator('.endoleap-mark-light').first().isVisible(), true);
     assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1), 'mobile home has no horizontal overflow');
+    for (const width of [390, 320]) {
+      await page.setViewportSize({ width, height: 844 });
+      assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1), 'Editorial home fits narrow screens');
+      const entry = await page.getByRole('navigation', {name: '主导航'}).getByRole('link', {name: /进入工作台/}).boundingBox();
+      assert.ok(entry && entry.x >= 0 && entry.x + entry.width <= width, 'Workspace entry is visible, not clipped');
+      assert.equal(await page.getByRole('link', {name: /去知识空间逛逛/}).getAttribute('href'), '/documents');
+      assert.equal(await page.getByRole('link', {name: '开始创作', exact: true}).getAttribute('href'), '/account?next=/workspace');
+    }
     console.log('Endoleap logos, both favicon paths, persisted home/canvas themes and artwork color isolation passed.');
   } finally { await browser.close(); }
 }

docs/docker-build-cache.md

@@ -0,0 +1,23 @@
+# Docker 构建上下文与缓存
+
+## 入口与忽略规则
+
+所有 CI 构建命令都在仓库根目录使用 `.` 作为 context，包括以 `-f` 选择的子项目 Dockerfile。统一使用根 `.dockerignore`，递归排除依赖目录、Git 元数据、本机环境文件、编译输出、测试证据及缓存；保留 `.env.example` 供 Compose 校验使用。
+
+普通的子目录 `.dockerignore` 不会自动叠加到根 context。当前 runner 使用 legacy builder，不依赖 Dockerfile 专属忽略文件或 BuildKit cache mount。若以后改用子目录 context，必须同时调整共享包与跨应用文件的输入路径，不能只在子目录添加忽略文件。
+
+## 依赖层与源码层
+
+- Wiki 的根 Dockerfile 是实际 CI 入口，`apps/waterfall-wiki/Dockerfile` 是对应副本，两者的功能内容保持同步；根文件额外保留镜像生命周期标签。
+- Web 应用安装前只复制自身清单、锁文件、workspace 配置和品牌包清单，满足 `workspace:*` 依赖发现。完整品牌包在安装后复制；颜色、Logo 或品牌脚本变化仍会重新编译应用，但不会仅因此重新下载依赖。
+- Python 从 `pyproject.toml` 读取固定运行依赖与构建后端要求，在独立依赖阶段安装。源码阶段安装当前包并运行单测，最终镜像仅继承系统运行环境并复制已验证的虚拟环境，不携带应用源码目录和测试目录。虚拟环境仍包含 pip 和构建后端，未声称完全剥离构建工具。
+- 品牌检查镜像只用于 CI。其 Python 图片校验依赖安装放在品牌源码之前，避免源码变化重新下载这些依赖。
+- 不因共享包缓存命中而漏掉消费者：品牌变更需触发 Wiki/Studio PR 检查和 main 发布。根忽略规则变化也触发相关检查。
+
+## 验证与限制
+
+构建、打包与产物验证只在已确认的 `ces-control` runner 执行。Python PR 运行镜像构建和单测，但只有 main push 才会发布 latest 标签。Web PR 与品牌检查沿用现有远程 Docker 验证流程。
+
+本次没有升级 Docker builder，也没有承诺消除 legacy builder 的镜像层提交耗时；缓存层调整后的实际收益需比较后续 CI 日志。源码变化仍需构建，持久测试环境和按影响范围选择测试属于后续 CI 调整。
+
+本机不新增 Dev Containers/Tilt 启动方式；这类方案需要单独确认本地运行和编译授权。

packages/brand/Dockerfile

@@ -3,10 +3,10 @@ WORKDIR /repo
 RUN corepack enable && corepack prepare pnpm@11.25.0 --activate
 COPY packages/brand/package.json packages/brand/pnpm-lock.yaml ./
 RUN pnpm install --frozen-lockfile --ignore-scripts
-COPY packages/brand/ ./
-RUN pnpm test && pnpm build && pnpm test:tailwind && pnpm test:types
 RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-venv \
     && rm -rf /var/lib/apt/lists/* \
     && python3 -m venv /opt/brand-python \
     && /opt/brand-python/bin/pip install --only-binary=:all: Pillow==13.0.0 resvg-py==0.5.0
+COPY packages/brand/ ./
+RUN pnpm test && pnpm build && pnpm test:tailwind && pnpm test:types
 RUN /opt/brand-python/bin/python tests/assets.py

scripts/verify-studio-visual.cjs

@@ -8,28 +8,47 @@ const assert=require('node:assert/strict');
  const now=Math.floor(Date.now()/1000),part=o=>Buffer.from(JSON.stringify(o)).toString('base64url');
  const content=part({alg:'HS256',typ:'JWT'})+'.'+part({iss:'prompt',aud:'prompt-web',sub:'shared',iat:now,exp:now+1200,jti:randomBytes(16).toString('hex')});
  const token=content+'.'+createHmac('sha256',Buffer.from(config.jwtKey,'hex')).update(content).digest('base64url');
+ const {navigateBrandDocument,visitBrowserDocument}=await import('../apps/waterfall-wiki/tests/brand-navigation.mjs');
  const browser=await chromium.launch({executablePath:'/usr/bin/chromium',headless:true,args:['--no-sandbox','--disable-dev-shm-usage']});
  const context=await browser.newContext({viewport:{width:1100,height:1000},deviceScaleFactor:1});
  await context.route('**/*',async route=>{const u=new URL(route.request().url());if(u.origin===origin)return route.continue({headers:{...route.request().headers(),Authorization:'Bearer '+token}});if(['data:','blob:'].includes(u.protocol))return route.continue();return route.abort()});
  const page=await context.newPage(),errors=[],images=[];
- page.on('pageerror',error=>errors.push({url:page.url(),message:error.message}));
+ page.setDefaultTimeout(60000);
+ page.on('pageerror',error=>errors.push({url:page.url(),message:error.message,stack:error.stack}));
  page.on('response',async response=>{if(response.request().resourceType()==='image'){const url=new URL(response.url());images.push({path:url.pathname+url.search,status:response.status(),type:response.headers()['content-type'],bytes:(await response.body().catch(()=>Buffer.alloc(0))).length})}});
+ // Wait for the actual document and application, not an idle background network.
+ // Shared navigation recovery is limited to safe GETs; assertions are never retried.
+ const visitDocument=async(url,interactive=false,reload=false)=>{
+  if(interactive)await visitBrowserDocument(page,url,reload);
+  else await navigateBrandDocument(timeout=>page.goto(url,{waitUntil:'domcontentloaded',timeout}),url);
+  await page.waitForFunction(()=>Array.from(document.images).every(img=>img.complete&&img.naturalWidth>0));
+  console.log('Production document ready:',new URL(url).pathname);
+ };
  // The retired catalogue is retained for existing API consumers, not a release UI gate.
  // Explicit legacy/diagnostic runs still exercise its full overflow assertions.
  const checkLegacy=process.argv.includes('--legacy-layouts')||process.argv.includes('--diagnose');
  const metrics=[];
  for(let i=1;i<=27&&checkLegacy;i++){
-  const id='ref-'+String(i).padStart(2,'0');await page.goto(base+'/studio/layouts/'+id,{waitUntil:'networkidle'});await page.locator('article.native-layout').screenshot({path:dir+'/'+id+'.png',style:'.page-tools{visibility:hidden}'});
+  const id='ref-'+String(i).padStart(2,'0');await visitDocument(base+'/studio/layouts/'+id);await page.locator('article.native-layout').screenshot({path:dir+'/'+id+'.png',style:'.page-tools{visibility:hidden}'});
   const m=await page.locator('article.native-layout').evaluate(el=>{
    const overflow=[...el.querySelectorAll('.native-copy')].filter(e=>e.scrollHeight>e.clientHeight+2||e.scrollWidth>e.clientWidth+2);
    return {id:el.dataset.layoutId,elements:el.querySelectorAll('[data-element]').length,width:el.clientWidth,height:el.clientHeight,overflow:overflow.map(e=>e.closest('[data-element]').dataset.element),overflowDetails:overflow.map(e=>{const style=getComputedStyle(e);return {id:e.closest('[data-element]').dataset.element,text:e.textContent,clientWidth:e.clientWidth,scrollWidth:e.scrollWidth,clientHeight:e.clientHeight,scrollHeight:e.scrollHeight,fontSize:style.fontSize,lineHeight:style.lineHeight,letterSpacing:style.letterSpacing,fontFamily:style.fontFamily,fontWeight:style.fontWeight,writingMode:style.writingMode}})};
   });metrics.push(m);await writeFile(dir+'/metrics.json',JSON.stringify({metrics,images,errors},null,2));
  }
  if(checkLegacy&&!process.argv.includes('--diagnose'))assert.deepEqual(metrics.filter(m=>m.overflow.length),[],'Default copy must fit every native slot');
- await page.goto(base+'/',{waitUntil:'networkidle'});await page.getByRole('heading',{name:/想法不该停在对话里/}).waitFor();await page.screenshot({path:dir+'/landing-desktop.png',fullPage:true});
+ await visitDocument(base+'/',true);await page.getByRole('heading',{name:/想法不该停在对话里/}).waitFor();await page.screenshot({path:dir+'/landing-desktop.png',fullPage:true});
+ // Capture the complete editorial home at both narrow breakpoints on the deployed server.
+ await page.getByRole('heading',{name:/给好奇心一点空间/}).waitFor();
+ for(const [width,name] of [[390,'landing-mobile'],[320,'landing-mobile-compact']]){
+  await page.setViewportSize({width,height:844});
+  assert.ok(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth+1),'Landing fits narrow screens');
+  const entry=await page.getByRole('navigation',{name:'主导航'}).getByRole('link',{name:/进入工作台/}).boundingBox();
+  assert.ok(entry&&entry.x>=0&&entry.x+entry.width<=width,'Landing workspace entry remains inside the viewport');
+  await page.screenshot({path:dir+'/'+name+'.png',fullPage:true});
+ }
  // Verify the public account flow in this fresh context, without submitting credentials.
  await page.setViewportSize({width:1128,height:959});
- await page.goto(base+'/account?next=/workspace',{waitUntil:'domcontentloaded'});
+ await visitDocument(base+'/account?next=/workspace',true);
  await page.locator('button[data-theme-ready="true"]').waitFor();
  await page.getByLabel('邮箱地址',{exact:true}).waitFor();
  assert.equal(await page.locator('aside').count(),0,'Authentication must not include a workspace sidebar');
@@ -44,43 +63,45 @@ const assert=require('node:assert/strict');
  await page.screenshot({path:dir+'/account-desktop.png',fullPage:true});
  await page.getByRole('button',{name:'创建账户',exact:true}).click();
  await page.getByRole('heading',{name:'创建你的账户',exact:true}).waitFor();
+ await page.waitForFunction(()=>document.querySelector('#account-content').getAnimations({subtree:true}).every(animation=>animation.playState!=='running'));
  await page.screenshot({path:dir+'/account-register.png',fullPage:true});
  await page.getByRole('button',{name:'登录',exact:true}).click();
+ await page.waitForFunction(()=>document.querySelector('#account-content').getAnimations({subtree:true}).every(animation=>animation.playState!=='running'));
  await page.setViewportSize({width:390,height:844});
  await accountFits();await accountControlsFit();
  await page.screenshot({path:dir+'/account-mobile.png',fullPage:true});
  await page.setViewportSize({width:320,height:568});await accountFits();await accountControlsFit();
  await page.screenshot({path:dir+'/account-mobile-compact.png',fullPage:true});
  await page.setViewportSize({width:1100,height:1000});
- await page.goto(base+'/graphic',{waitUntil:'networkidle'});
+ await visitDocument(base+'/graphic',true);
  assert.equal(new URL(page.url()).pathname,'/graphic');
  await page.getByRole('button',{name:'添加文字',exact:true}).waitFor({state:'visible'});
  assert.equal(await page.locator('.library-item').count(),0,'Old catalog is retired from the entry page');
  await page.getByRole('button',{name:'添加文字',exact:true}).click();
  await page.getByRole('textbox',{name:'文字内容',exact:true}).fill('Studio 线上验收');
- await page.reload({waitUntil:'networkidle'});
+ await visitDocument(page.url(),true,true);
  assert.ok(await page.evaluate(()=>JSON.parse(localStorage.getItem('studio.graphic.v1')).items.some(i=>i.text==='Studio 线上验收')));
  await page.screenshot({path:dir+'/graphic-desktop.png',fullPage:true});
- await page.goto(base+'/infinite_canvas',{waitUntil:'networkidle'});
+ await visitDocument(base+'/infinite_canvas',true);
  assert.equal(new URL(page.url()).pathname,'/infinite_canvas');
  await page.getByRole('button',{name:'添加笔记',exact:true}).waitFor({state:'visible'});
  await page.screenshot({path:dir+'/infinite-canvas-desktop.png',fullPage:true});
  const verify=JSON.parse(await readFile('/tmp/studio-library/verification.json','utf8'));
- for(const d of verify.results){await page.goto(base+d.url,{waitUntil:'networkidle'});assert.equal(await page.locator('img').count(),1);const current=await page.locator('img').evaluate(img=>({src:img.currentSrc,complete:img.complete,width:img.naturalWidth}));assert.ok(current.complete&&current.width>0);assert.equal(new URL(current.src).pathname,'/api/preview');await page.locator('article.native-layout').screenshot({path:dir+'/'+d.layoutId+'-saved.png',style:'.page-tools{visibility:hidden}'});
+ for(const d of verify.results){await visitDocument(base+d.url);assert.equal(await page.locator('img').count(),1);const current=await page.locator('img').evaluate(img=>({src:img.currentSrc,complete:img.complete,width:img.naturalWidth}));assert.ok(current.complete&&current.width>0);assert.equal(new URL(current.src).pathname,'/api/preview');await page.locator('article.native-layout').screenshot({path:dir+'/'+d.layoutId+'-saved.png',style:'.page-tools{visibility:hidden}'});
   assert.equal(new URL(page.url()).pathname,'/studio/template-layout');
   assert.equal(await page.locator('button,input,textarea,select,[contenteditable],.page-tools,.workbench-top').count(),0);
   await page.locator('.native-copy').first().dblclick();await page.locator('.native-copy').first().dispatchEvent('contextmenu');
   assert.equal(await page.locator('button,input,textarea,select,[contenteditable],.workbench-top').count(),0);
   const plain=await browser.newContext({viewport:{width:1100,height:1000},javaScriptEnabled:false});
   await plain.route('**/*',async route=>{const u=new URL(route.request().url());if(u.origin===origin)return route.continue({headers:{...route.request().headers(),Authorization:'Bearer '+token}});return route.abort()});
-  const direct=await plain.newPage();await direct.goto(base+d.url,{waitUntil:'networkidle'});assert.equal(await direct.locator('article[data-design-id="'+d.id+'"]').count(),1);assert.ok((await direct.locator('article').innerText()).includes('API 验收'));await plain.close();
+  const direct=await plain.newPage();await navigateBrandDocument(timeout=>direct.goto(base+d.url,{waitUntil:'domcontentloaded',timeout}),base+d.url);assert.equal(await direct.locator('article[data-design-id="'+d.id+'"]').count(),1);assert.ok((await direct.locator('article').innerText()).includes('API 验收'));await plain.close();
  }
- for(const slug of ['learning-skills-template','layout-selection']){await page.goto(base+'/studio/ideas/'+slug,{waitUntil:'networkidle'});await page.screenshot({path:dir+'/tool-'+slug+'.png',fullPage:true})}
- await page.setViewportSize({width:390,height:844});await page.goto(base+'/graphic',{waitUntil:'networkidle'});assert.ok(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));await page.screenshot({path:dir+'/graphic-mobile.png',fullPage:true});
- await page.goto(base+verify.results[0].url,{waitUntil:'networkidle'});await page.screenshot({path:dir+'/standard-mobile.png',fullPage:true});
- await page.goto(base+'/categories?category='+encodeURIComponent('文档入口'),{waitUntil:'domcontentloaded',timeout:60000});await page.getByRole('navigation',{name:'系统标签分类',exact:true}).waitFor({state:'visible'});assert.equal(await page.locator('.discovery-card').count(),3);await page.waitForFunction(()=>Array.from(document.querySelectorAll('.discovery-card img')).every(img=>img.complete&&img.naturalWidth>0),null,{timeout:60000});await page.screenshot({path:dir+'/document-entries.png',fullPage:true});
+ for(const slug of ['learning-skills-template','layout-selection']){await visitDocument(base+'/studio/ideas/'+slug);await page.screenshot({path:dir+'/tool-'+slug+'.png',fullPage:true})}
+ await page.setViewportSize({width:390,height:844});await visitDocument(base+'/graphic',true);assert.ok(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));await page.screenshot({path:dir+'/graphic-mobile.png',fullPage:true});
+ await visitDocument(base+verify.results[0].url);await page.screenshot({path:dir+'/standard-mobile.png',fullPage:true});
+ await visitDocument(base+'/categories?category='+encodeURIComponent('文档入口'),true);await page.getByRole('navigation',{name:'系统标签分类',exact:true}).waitFor({state:'visible'});assert.equal(await page.locator('.discovery-card').count(),3);await page.waitForFunction(()=>Array.from(document.querySelectorAll('.discovery-card img')).every(img=>img.complete&&img.naturalWidth>0),null,{timeout:60000});await page.screenshot({path:dir+'/document-entries.png',fullPage:true});
  await writeFile(dir+'/metrics.json',JSON.stringify({metrics,images,errors},null,2));
  assert.equal(images.filter(r=>new URL(r.path,base).pathname.startsWith('/api/media/')).length,0,'Display must never fetch originals');if(!process.argv.includes('--diagnose'))assert.equal(errors.length,0,JSON.stringify(errors));for(const image of images){if(/^\/(?:studio\/)?brand\/(?:logo-light|logo-dark|icon-dark)\.svg$/.test(new URL(image.path,base).pathname)){assert.equal(image.status,200);assert.match(image.type,/image\/svg\+xml/);continue;}assert.equal(new URL(image.path,base).pathname,'/api/preview');assert.equal(image.status,200);assert.equal(image.type,'image/webp');assert.ok(image.bytes>0&&image.bytes<=220000)}
  await writeFile(dir+'/metrics.json',JSON.stringify({metrics,images,errors},null,2));await browser.close();
  console.log(JSON.stringify({diagnostic:process.argv.includes('--diagnose'),legacyLayoutsChecked:checkLegacy,legacyPages:metrics.length,errors:errors.length,displayImages:images.length,originalImageRequests:0,overflow:metrics.filter(m=>m.overflow.length)}));
-})().catch(e=>{console.error(e.message);process.exit(1)});
+})().catch(e=>{console.error(e.stack||e.message);process.exit(1)});