diff --git a/.orchestrator/architecture-summary.md b/.orchestrator/architecture-summary.md new file mode 100644 index 000000000..c040593cd --- /dev/null +++ b/.orchestrator/architecture-summary.md @@ -0,0 +1,158 @@ +# Admin SDK Tutorial Prototype — Architecture Summary + +## What we built + +We built a prototype package at `packages/admin-sdk-tutorial` that demonstrates an interactive, browser-based learning flow for the Meteor Admin SDK. + +The prototype includes: + +- a split tutorial layout with lesson content on the left +- an in-browser code editor on the right +- a dummy admin preview shell +- a small mocked Admin SDK bridge +- browser-side code execution for learner input +- three end-to-end lessons: + - notifications + - menu items + - locations / positions + +## Main architecture pieces + +### 1. Tutorial shell + +The app shell lives in `App.vue` and coordinates: + +- active lesson selection +- current editor code +- reset/run state +- runtime state for the preview +- execution feedback for the output panel + +### 2. Lesson model + +Lesson content is currently hardcoded in `src/lessons/lessons.ts` and typed in `src/types/lesson.ts`. + +Each lesson defines: + +- title and summary +- explanatory description +- learning objective +- starter code +- preview/output labels + +### 3. Editor layer + +The editor is intentionally lightweight: + +- `CodeEditorPanel.vue` +- single-file editing (`main.ts` affordance) +- textarea-based input +- reset and run controls + +This keeps the prototype simple while proving the interaction model. + +### 4. Dummy admin runtime + +The preview is rendered through: + +- `PreviewPanel.vue` +- `DummyAdminShell.vue` + +The dummy admin visualizes: + +- notifications +- navigation entries +- extension surfaces / positions + +It is not intended to mirror the real Shopware Administration UI exactly. It is designed to teach concepts with minimal visual noise. + +### 5. Runtime state model + +Preview state is represented as structured runtime data in `src/types/runtime.ts` and initialized through `src/runtime/createRuntimeState.ts`. + +This separates: + +- lesson content +- runtime/UI state +- execution behavior + +### 6. Mock Admin SDK bridge + +`src/runtime/sdkBridge.ts` provides a narrow bridge API for the prototype: + +- `sdk.notification.dispatch(...)` +- `sdk.menu.add(...)` +- `sdk.location.render(...)` + +Instead of talking to a real admin host, these methods mutate the dummy runtime state. + +### 7. Code execution flow + +`src/runtime/executeLessonCode.ts` executes learner code in the browser using a constrained runtime approach. + +The flow is: + +1. reset runtime state for the active lesson +2. execute learner code with access to the mock `sdk` +3. update preview from bridge mutations +4. show success/error feedback in the output panel + +## Why this structure works + +This prototype architecture is useful because it keeps responsibilities separate: + +- lessons define teaching content +- the editor manages learner input +- execution runs user code +- the bridge translates API calls into state changes +- the preview only renders runtime state + +That makes it easier to evolve the prototype without tightly coupling everything together. + +--- + +# What a second pass could look like + +## UX and visual polish + +- make the dummy admin feel more product-like while staying minimal +- improve typography, spacing, and hierarchy +- reduce duplicated information between toast, empty state, and output areas +- improve mobile ergonomics further + +## Editor improvements + +- replace textarea with a richer code editor +- support locked/editable regions +- add inline hints or lesson tasks +- add formatting or syntax highlighting + +## Better execution model + +- move from naive `Function(...)` execution to a safer constrained execution layer +- support more structured lesson scaffolds +- capture richer runtime diagnostics + +## Stronger lesson system + +- add validation rules per lesson +- define expected outcomes instead of only freeform execution +- move lesson content into markdown/MDX or another authoring format + +## More realistic SDK teaching + +- expand the bridge with more Admin SDK APIs +- add more realistic host events and state transitions +- simulate communication patterns more explicitly + +## Better preview fidelity + +- represent locations and positions with more accurate conceptual models +- add clearer UI states for registered menu items and notifications +- introduce optional “host frame vs extension frame” visualization if needed + +## Productization path + +- decide whether this should remain a package app or move into a dedicated docs/tutorial surface +- define how the tutorial would integrate with Admin SDK documentation +- add analytics/progress only if the concept is validated first diff --git a/.orchestrator/final-architecture-summary.md b/.orchestrator/final-architecture-summary.md new file mode 100644 index 000000000..9052c1056 --- /dev/null +++ b/.orchestrator/final-architecture-summary.md @@ -0,0 +1,93 @@ +# Admin SDK Tutorial Prototype — Final Architecture Summary + +## What the prototype now does + +The tutorial prototype now runs the **real Meteor Admin SDK** inside lesson iframes and uses a **dummy admin host shell** in the parent app to handle the resulting postMessage traffic. + +This means the learner-facing code is no longer powered by a fake SDK bridge for the main lessons. + +## Runtime architecture + +### 1. Parent app = tutorial shell + dummy host + +The main Vue app is responsible for: + +- lesson selection +- editor state +- preview shell UI +- output/status UI +- host-side Admin SDK handler registration +- simplified dummy admin state rendering + +### 2. Lesson runtime = real iframe context + +Each lesson run is executed in an iframe runtime that: + +- imports the real `@shopware-ag/meteor-admin-sdk` +- receives lesson code from the parent +- executes that code in an iframe context +- communicates with the parent through real SDK `postMessage` traffic + +### 3. Host-side handler layer + +The parent host listens for and handles real SDK messages, including: + +- `__registerWindow__` +- `notificationDispatch` +- `menuItemAdd` +- `uiComponentSectionRenderer` +- `locationUpdateHeight` + +These handlers translate SDK messages into simplified dummy-admin UI state. + +## Lesson architecture + +### Notifications + +- learner code uses the real notification API shape +- iframe sends real notification traffic +- host renders the notification in the dummy admin shell + +### Menu items + +- learner code uses `ui.menu.addMenuItem(...)` +- iframe sends real menu registration traffic +- host updates dummy sidebar navigation + +### Locations / positions + +- learner code uses real concepts like: + - `location.MAIN_HIDDEN` + - `ui.componentSection.add(...)` + - `location.is(...)` + - `location.updateHeight(...)` +- host renders simplified extension surfaces +- matching location iframes are mounted into the chosen host slot + +## UI architecture + +The visible tutorial experience has four main parts: + +- tutorial sidebar +- real code editor +- dummy admin preview shell +- output/status panel + +The preview uses a landscape-oriented host frame so the dummy admin feels closer to a real monitor-based admin environment. + +## Current strengths + +- real SDK package is used for the main lessons +- real iframe/host message flow is in place +- simplified host shell is enough to teach the concepts clearly +- success/error states are visible to the learner +- desktop and mobile layouts both work + +## Remaining minor quirks + +- the iframe runtime display can still show slightly imperfect code text across repeated runs +- some preserved error-state visuals could still be polished further + +## Bottom line + +The prototype now teaches the Admin SDK with a **real runtime architecture** and a **simplified host UI**, rather than only simulating the API surface. diff --git a/.orchestrator/implementation-brief.md b/.orchestrator/implementation-brief.md new file mode 100644 index 000000000..0ffc22018 --- /dev/null +++ b/.orchestrator/implementation-brief.md @@ -0,0 +1,246 @@ +# Interactive Admin SDK Tutorial Prototype — Implementation Brief + +## Goal + +Build a first interactive prototype for learning the Meteor Admin SDK inside this monorepo. + +The prototype should: + +- be inspired by the Solid tutorial split layout +- not depend on TutorialKit or StackBlitz +- run entirely in the browser +- let the user edit code live +- execute that code against a minimal dummy admin runtime +- focus on understanding Admin SDK concepts, not replicating the full Shopware Administration UI + +## Confirmed Direction + +- **Deliverable:** clickable UI prototype +- **Monorepo placement preference:** additional package/app in the repo +- **Coding experience:** real editable code running in-browser +- **Initial lesson topics:** notifications, menu items, locations/positions +- **Layout direction:** Solid-like split layout +- **Dummy admin fidelity:** minimal wireframe / lightweight UI +- **Process:** implementation brief first, then approval before coding + +## Product Intent + +The user should learn Admin SDK concepts by writing code directly in the browser and immediately seeing how the dummy admin reacts. + +The dummy admin should be deliberately minimal. It only needs enough UI and behavior so learners understand concepts like: + +- triggering notifications +- adding navigation or menu items +- rendering content into locations / positions + +For locations and position IDs, a simplified visualization is sufficient, e.g. cards with clearly labeled iframe-like surfaces. + +## Monorepo Placement + +The user explicitly chose: + +`packages/admin-sdk-tutorial` + +Even though `examples/` would also fit a prototype app, all implementation work should now assume the tutorial lives under `packages/`. + +## Suggested Stack + +- Vue 3 +- Vite +- TypeScript +- optional reuse of `@shopware-ag/meteor-component-library` for selected UI pieces +- reuse/reference of `@shopware-ag/meteor-admin-sdk` where helpful, but mock runtime behavior locally for the prototype + +## Prototype Scope + +This first prototype should prove the overall learning experience, not solve the full long-term platform. + +### Included + +- split-screen tutorial shell +- lesson/navigation panel on the left +- in-browser code editor on the right +- live preview area on the right +- minimal dummy admin runtime +- mocked Admin SDK behavior for the first concepts +- three prototype lessons/steps + +### Excluded for now + +- full production authoring system +- persistent learner progress +- backend services or storage +- full Shopware Administration embedding +- full Admin SDK API coverage +- general-purpose WebContainer-like project sandbox +- production-grade assessment engine + +## Proposed UX Structure + +## Layout + +- **Left column** + - lesson title + - explanation/content + - step navigation + - hints / expected outcome +- **Right column** + - editor tabs or a compact single-file editor + - live preview of the dummy admin + - optional output/console panel + +## Lessons for the Prototype + +### 1. Notifications + +Learner writes code that triggers a notification. + +Preview behavior: + +- display a toast/message area in the dummy admin +- show notification type and text clearly + +### 2. Menu items + +Learner writes code that adds a menu item. + +Preview behavior: + +- update a fake navigation/sidebar area +- make the new item visible and understandable immediately + +### 3. Locations / positions + +Learner writes code that targets extension surfaces. + +Preview behavior: + +- show simplified location containers +- use cards/panels with labeled slots +- visually communicate which content lands in which location/position + +## Proposed Technical Architecture + +### 1. Tutorial Shell + +A dedicated app that renders: + +- lesson content +- active step metadata +- editor state +- preview state + +For the prototype, lesson content can be hardcoded in TypeScript/JSON rather than introducing a full content pipeline. + +### 2. Editor Layer + +For the prototype, keep the editing model intentionally small: + +- preferably a single editable file per lesson (e.g. `main.ts` or `lesson.ts`) +- support reset to initial state +- optionally support small locked/unlocked regions later + +### 3. Execution / Sandbox Layer + +Run learner code entirely in the browser. + +Recommended approach for the prototype: + +- sandbox the preview in an iframe +- inject a controlled runtime/mock bridge +- execute only the code needed for the lesson environment + +Avoid building a fully generic multi-file browser IDE at this stage. + +### 4. Dummy Admin Runtime + +Build a minimal fake admin shell that exposes only the UI surfaces needed by the lessons. + +Suggested UI primitives: + +- sidebar / navigation list +- header or toolbar area +- notification area +- content cards/panels +- labeled extension slots / pseudo-iframes + +The visual language should remain lightweight and instructional, not a copy of the real Shopware UI. + +### 5. Mock Admin SDK Bridge + +Provide a thin compatibility layer so learner code can call familiar APIs while the prototype runtime translates those calls into dummy admin UI updates. + +Core initial behaviors: + +- create/show notifications +- register/add menu items +- register/render content into named locations/positions + +## Architectural Principles + +- optimize for teaching clarity over visual realism +- keep the runtime deterministic and easy to inspect +- prefer a constrained lesson environment over a generic platform +- keep lessons small and focused +- make the relation between learner code and UI result obvious + +## Key Open Decisions / Risks + +### 1. Placement: `examples/` vs `packages/` + +The current repo structure suggests `examples/` is the best fit for a prototype app, even though the initial idea mentioned an additional package. + +### 2. Fidelity of the mock SDK + +We need to decide how closely the prototype runtime should mirror the real Admin SDK. + +Recommendation: + +- keep it minimal for now +- stay semantically close where easy +- avoid early overinvestment in API parity + +### 3. Editor scope + +Single-file editing is the fastest way to validate the tutorial concept. + +Recommendation: + +- start with single-file editing +- add multi-file support only if it becomes necessary for lesson clarity + +### 4. Browser execution complexity + +A fully general code execution environment can become expensive quickly. + +Recommendation: + +- use a narrowly scoped execution model for prototype lessons +- do not emulate a full project sandbox yet + +## Recommended Build Plan + +1. create the prototype app in the monorepo +2. implement the split tutorial shell +3. add a minimal browser editor +4. add sandboxed preview execution +5. build the dummy admin shell +6. implement mock Admin SDK actions for notifications, menu items, and locations/positions +7. create three prototype lessons +8. polish interaction and visual clarity + +## Working Assumptions for Subagents + +- This is a **prototype**, not a production tutorial system. +- The UI should be **minimal and instructional**. +- The result should feel close to the **Solid tutorial interaction model**. +- The learner must be able to **edit code directly in the browser**. +- Everything should happen **client-side in the browser**. +- Avoid introducing dependencies on StackBlitz/TutorialKit/WebContainer-style infrastructure. +- Prefer the existing monorepo conventions and lightweight reuse over building a large new framework. + +## Confirmed Package Target + +Proceed with implementation in: + +`packages/admin-sdk-tutorial` diff --git a/.orchestrator/implementation-plan.md b/.orchestrator/implementation-plan.md new file mode 100644 index 000000000..8acc75b71 --- /dev/null +++ b/.orchestrator/implementation-plan.md @@ -0,0 +1,720 @@ +# Interactive Admin SDK Tutorial Prototype — Implementation Plan + +## Plan Context + +- The prototype must live under `packages/` +- Recommended target package: `packages/admin-sdk-tutorial` +- The work is intentionally split into very small executable tasks +- Each task should be scoped to roughly **5 minutes or less** +- This plan is optimized for delegation to subagents + +## Execution Rules + +- Complete tasks in order unless explicitly marked parallelizable +- Keep each task narrowly scoped +- Prefer visible progress over early abstraction +- Do not expand scope beyond the prototype goals in `implementation-brief.md` + +--- + +## Phase 1 — Package Setup + +### 1.1 Create package folder structure +- Create `packages/admin-sdk-tutorial` +- Create initial `src/` folder +- Create placeholder folders for `components/`, `lessons/`, `runtime/`, and `types/` + +### 1.2 Add package manifest +- Create `packages/admin-sdk-tutorial/package.json` +- Set package name +- Mark package as private if appropriate for prototype stage +- Add initial scripts (`dev`, `build`, `preview`, `typecheck`) + +### 1.3 Add TypeScript config +- Create local `tsconfig.json` +- Align with repo conventions where possible + +### 1.4 Add Vite config +- Create `vite.config.ts` +- Enable Vue support + +### 1.5 Add app HTML entry +- Create `index.html` +- Add root mount element + +### 1.6 Add source entrypoint +- Create `src/main.ts` +- Mount the root Vue app + +### 1.7 Add root app component +- Create `src/App.vue` +- Render simple placeholder text to confirm bootstrapping + +### 1.8 Register workspace dependencies +- Add initial dependencies and devDependencies +- Use workspace references where needed + +### 1.9 Ensure package is included by workspace conventions +- Verify no extra workspace configuration is required +- Confirm package path matches monorepo patterns + +--- + +## Phase 2 — Prototype Shell + +### 2.1 Replace placeholder with split layout shell +- Create left and right column layout in `App.vue` +- Add semantic container sections + +### 2.2 Add base shell styling +- Add initial layout CSS +- Ensure full-height app shell works + +### 2.3 Create lesson sidebar component +- Add `src/components/TutorialSidebar.vue` +- Render title, description, and step list placeholders + +### 2.4 Create workspace panel component +- Add `src/components/TutorialWorkspace.vue` +- Render editor and preview placeholders + +### 2.5 Wire shell components into root app +- Replace inline layout with reusable components + +### 2.6 Add mobile-safe fallback layout behavior +- Add basic responsive stacking behavior +- Do not over-polish yet + +--- + +## Phase 3 — Lesson Data Model + +### 3.1 Create lesson type definitions +- Add `src/types/lesson.ts` +- Define minimal lesson and step interfaces + +### 3.2 Create prototype lesson data file +- Add `src/lessons/lessons.ts` +- Seed three lessons: notifications, menu items, locations/positions + +### 3.3 Add active lesson state in app shell +- Store selected lesson/step in root state + +### 3.4 Render lesson metadata in sidebar +- Show active title, summary, and step list + +### 3.5 Add lesson switching behavior +- Enable click-to-select lesson/step + +### 3.6 Add reset-on-lesson-change behavior +- Reset editor/preview state when changing lessons + +--- + +## Phase 4 — Editor Prototype + +### 4.1 Create editor component shell +- Add `src/components/CodeEditorPanel.vue` +- Render labeled editor area placeholder + +### 4.2 Add editable text area as first editor +- Use a textarea-based implementation first +- Do not introduce a heavy editor dependency yet + +### 4.3 Bind editor to lesson starter code +- Load starter code for active lesson + +### 4.4 Add local editor state updates +- Keep current code reactive + +### 4.5 Add reset button +- Reset editor content back to lesson starter code + +### 4.6 Add basic file/tab affordance +- Show a single file name like `main.ts` +- Keep actual editing single-file only + +--- + +## Phase 5 — Preview Shell + +### 5.1 Create preview container component +- Add `src/components/PreviewPanel.vue` +- Render preview header and placeholder body + +### 5.2 Add dummy admin shell component +- Add `src/components/DummyAdminShell.vue` +- Render simple nav, content area, and notification region + +### 5.3 Add preview composition +- Mount dummy admin shell inside preview panel + +### 5.4 Add output/status area +- Render a small status or output region below preview + +### 5.5 Add empty-state messaging +- Show friendly message before first successful run if needed + +--- + +## Phase 6 — Runtime State Model + +### 6.1 Create runtime type definitions +- Add `src/types/runtime.ts` +- Define notification, menu item, and location state types + +### 6.2 Create runtime state factory +- Add `src/runtime/createRuntimeState.ts` +- Return initial empty runtime state + +### 6.3 Add runtime state to root app +- Store active preview/runtime state at app level + +### 6.4 Pass runtime state into preview shell +- Bind reactive runtime state into dummy admin UI + +### 6.5 Add runtime reset helper +- Reset runtime to lesson defaults before each run + +--- + +## Phase 7 — Mock Admin SDK Bridge + +### 7.1 Create bridge module skeleton +- Add `src/runtime/sdkBridge.ts` +- Export minimal bridge factory + +### 7.2 Add notification API surface +- Implement method(s) for creating notifications + +### 7.3 Add menu item API surface +- Implement method(s) for registering menu items + +### 7.4 Add location registration API surface +- Implement method(s) for registering location content + +### 7.5 Connect bridge methods to runtime state +- Ensure bridge mutates preview state deterministically + +### 7.6 Add bridge reset behavior +- Ensure each execution starts cleanly + +--- + +## Phase 8 — In-Browser Execution + +### 8.1 Create execution module skeleton +- Add `src/runtime/executeLessonCode.ts` +- Define a narrow execution entrypoint + +### 8.2 Define execution input contract +- Pass current code and bridge/runtime context into executor + +### 8.3 Implement first naive evaluation flow +- Use a constrained prototype approach suitable for the current lesson code shape + +### 8.4 Capture runtime errors +- Return execution errors instead of crashing the app + +### 8.5 Trigger execution from UI +- Add a Run button or initial autorun behavior + +### 8.6 Reset runtime before execution +- Ensure each run starts from fresh lesson state + +### 8.7 Surface errors in output panel +- Show readable execution error messages + +--- + +## Phase 9 — Notifications Lesson + +### 9.1 Add notification lesson starter code +- Seed realistic starter code for notification concept + +### 9.2 Add notification lesson text +- Explain the concept and expected result + +### 9.3 Render notifications in dummy admin +- Show toast/message items in preview + +### 9.4 Verify notification code path +- Ensure starter code produces visible result + +### 9.5 Refine notification visuals +- Make the result easy to understand at a glance + +--- + +## Phase 10 — Menu Items Lesson + +### 10.1 Add menu item lesson starter code +- Seed realistic starter code for menu registration + +### 10.2 Add menu item lesson text +- Explain what the learner should observe + +### 10.3 Render menu items in dummy sidebar +- Show registered menu items in navigation area + +### 10.4 Verify menu registration code path +- Ensure the preview updates correctly + +### 10.5 Refine menu visuals +- Make added items visually distinct from static shell UI + +--- + +## Phase 11 — Locations / Positions Lesson + +### 11.1 Add locations lesson starter code +- Seed starter code for location/position behavior + +### 11.2 Add locations lesson text +- Explain named slots and why they matter + +### 11.3 Add labeled location containers to dummy admin +- Render two or more clear extension surfaces + +### 11.4 Render registered location content +- Show learner-defined content inside the correct surface + +### 11.5 Verify positions concept visually +- Make placement obvious without copying full Shopware UI + +### 11.6 Refine location card visuals +- Improve labels and boundaries for comprehension + +--- + +## Phase 12 — UX Polish + +### 12.1 Add lesson progress affordance +- Show current lesson/step state clearly + +### 12.2 Improve shell spacing and typography +- Make the tutorial easier to scan + +### 12.3 Improve button labels and helper text +- Reduce ambiguity in controls + +### 12.4 Improve preview empty/error states +- Make failure and reset flows understandable + +### 12.5 Add minimal branding alignment +- Keep visuals lightweight and consistent with repo context + +--- + +## Phase 13 — Verification + +### 13.1 Start dev app and verify boot +- Confirm the package runs locally + +### 13.2 Verify lesson switching +- Confirm editor and preview state update correctly + +### 13.3 Verify notifications lesson manually +- Confirm learner edits affect preview + +### 13.4 Verify menu items lesson manually +- Confirm learner edits affect preview + +### 13.5 Verify locations lesson manually +- Confirm learner edits affect preview + +### 13.6 Verify responsive layout manually +- Check desktop and narrow viewport behavior + +### 13.7 Fix any obvious prototype regressions +- Resolve blocking issues only + +--- + +## Optional Follow-Up Tasks + +These are intentionally out of current scope, but may be scheduled later. + +### O.1 Replace textarea with richer code editor +### O.2 Add locked/editable code regions +### O.3 Add inline task validation +### O.4 Move lesson content to markdown/MDX-like source +### O.5 Add browser-based visual review pass +### O.6 Expand supported Admin SDK concepts + +--- + +## Suggested First Delegation Batch + +If subagents are used, a good first sequence is: + +1. Phase 1 — Package Setup +2. Phase 2 — Prototype Shell +3. Phase 3 — Lesson Data Model +4. Phase 4 — Editor Prototype +5. Phase 5 — Preview Shell + +Then continue with runtime and lesson behavior. + +--- + +## Delegation Batches + +The tasks above are intentionally tiny. For actual execution, they should be grouped into small delegation batches that still preserve fast feedback and low merge risk. + +Each batch below is designed to be: + +- coherent enough for a subagent to complete independently +- small enough to review quickly +- low-risk to integrate before the next batch starts + +## Batch A — Scaffold the package + +### Goal +Create a bootable package under `packages/admin-sdk-tutorial` that renders a placeholder Vue app. + +### Includes +- 1.1 Create package folder structure +- 1.2 Add package manifest +- 1.3 Add TypeScript config +- 1.4 Add Vite config +- 1.5 Add app HTML entry +- 1.6 Add source entrypoint +- 1.7 Add root app component +- 1.8 Register workspace dependencies +- 1.9 Ensure package is included by workspace conventions + +### Suggested agent type +- `general` or direct implementation by parent session + +### Expected output +- package exists +- app boots locally +- placeholder UI renders + +### Validation +- install/build tooling resolves +- dev server starts +- root component mounts successfully + +## Batch B — Build the split tutorial shell + +### Goal +Establish the Solid-inspired split-screen experience with a stable left/right layout. + +### Includes +- 2.1 Replace placeholder with split layout shell +- 2.2 Add base shell styling +- 2.3 Create lesson sidebar component +- 2.4 Create workspace panel component +- 2.5 Wire shell components into root app +- 2.6 Add mobile-safe fallback layout behavior + +### Suggested agent type +- `general` + +### Expected output +- tutorial shell exists +- left panel shows lesson area placeholder +- right panel shows workspace area placeholder +- narrow viewport stacks acceptably + +### Validation +- desktop layout reads clearly +- responsive fallback does not break app shell + +## Batch C — Add lesson data and navigation + +### Goal +Make the shell data-driven with three prototype lessons and clickable switching. + +### Includes +- 3.1 Create lesson type definitions +- 3.2 Create prototype lesson data file +- 3.3 Add active lesson state in app shell +- 3.4 Render lesson metadata in sidebar +- 3.5 Add lesson switching behavior +- 3.6 Add reset-on-lesson-change behavior + +### Suggested agent type +- `general` + +### Expected output +- three lessons exist in structured data +- lesson list renders in sidebar +- active lesson can be changed +- shell state resets when lesson changes + +### Validation +- lesson titles and descriptions render correctly +- switching updates the active view without stale state + +## Batch D — Add the first editor experience + +### Goal +Give the learner a simple but working in-browser editing area. + +### Includes +- 4.1 Create editor component shell +- 4.2 Add editable text area as first editor +- 4.3 Bind editor to lesson starter code +- 4.4 Add local editor state updates +- 4.5 Add reset button +- 4.6 Add basic file/tab affordance + +### Suggested agent type +- `general` + +### Expected output +- active lesson starter code loads in editor +- learner can edit code +- reset restores starter content +- UI looks like a lightweight single-file editor + +### Validation +- edits are reactive +- lesson change reloads correct starter code +- reset behaves deterministically + +## Batch E — Add preview shell and dummy admin skeleton + +### Goal +Create the visual target area where Admin SDK behavior will appear. + +### Includes +- 5.1 Create preview container component +- 5.2 Add dummy admin shell component +- 5.3 Add preview composition +- 5.4 Add output/status area +- 5.5 Add empty-state messaging + +### Suggested agent type +- `general` + +### Expected output +- preview area is visible +- dummy admin shell renders with nav/content/notification regions +- output panel exists for status/errors + +### Validation +- shell is visually understandable without any execution yet +- preview and output areas remain stable during lesson switching + +## Batch F — Add runtime state plumbing + +### Goal +Introduce deterministic preview state that the mock SDK bridge can mutate. + +### Includes +- 6.1 Create runtime type definitions +- 6.2 Create runtime state factory +- 6.3 Add runtime state to root app +- 6.4 Pass runtime state into preview shell +- 6.5 Add runtime reset helper + +### Suggested agent type +- `general` + +### Expected output +- runtime state model exists +- preview consumes runtime state reactively +- runtime can be reset cleanly + +### Validation +- reset returns preview to baseline state +- no lesson data is hardcoded into preview rendering paths + +## Batch G — Implement the mock Admin SDK bridge + +### Goal +Create a narrow bridge API that converts learner actions into dummy admin state changes. + +### Includes +- 7.1 Create bridge module skeleton +- 7.2 Add notification API surface +- 7.3 Add menu item API surface +- 7.4 Add location registration API surface +- 7.5 Connect bridge methods to runtime state +- 7.6 Add bridge reset behavior + +### Suggested agent type +- `general` + +### Expected output +- bridge exposes minimal APIs for all three concepts +- bridge updates runtime state deterministically + +### Validation +- isolated smoke calls update runtime state as expected +- reset clears all prior bridge effects + +## Batch H — Add code execution flow + +### Goal +Execute learner code in-browser and connect it to the mock bridge. + +### Includes +- 8.1 Create execution module skeleton +- 8.2 Define execution input contract +- 8.3 Implement first naive evaluation flow +- 8.4 Capture runtime errors +- 8.5 Trigger execution from UI +- 8.6 Reset runtime before execution +- 8.7 Surface errors in output panel + +### Suggested agent type +- `general` + +### Expected output +- learner code can run from the UI +- bridge methods affect preview +- execution errors are visible but non-fatal + +### Validation +- success path updates preview +- error path updates output panel and preserves app stability + +## Batch I — Finish the notifications lesson + +### Goal +Deliver the first complete end-to-end teaching slice. + +### Includes +- 9.1 Add notification lesson starter code +- 9.2 Add notification lesson text +- 9.3 Render notifications in dummy admin +- 9.4 Verify notification code path +- 9.5 Refine notification visuals + +### Suggested agent type +- `general` + +### Expected output +- notification lesson is understandable and runnable +- learner edits visibly change notification behavior + +### Validation +- starter code produces a visible notification +- modified code changes message/type/behavior predictably + +## Batch J — Finish the menu items lesson + +### Goal +Deliver the second complete teaching slice. + +### Includes +- 10.1 Add menu item lesson starter code +- 10.2 Add menu item lesson text +- 10.3 Render menu items in dummy sidebar +- 10.4 Verify menu registration code path +- 10.5 Refine menu visuals + +### Suggested agent type +- `general` + +### Expected output +- menu lesson is understandable and runnable +- learner edits visibly change the sidebar result + +### Validation +- starter code adds menu content to preview +- modified code changes label/order/appearance predictably + +## Batch K — Finish the locations / positions lesson + +### Goal +Deliver the third complete teaching slice focused on comprehension of extension placement. + +### Includes +- 11.1 Add locations lesson starter code +- 11.2 Add locations lesson text +- 11.3 Add labeled location containers to dummy admin +- 11.4 Render registered location content +- 11.5 Verify positions concept visually +- 11.6 Refine location card visuals + +### Suggested agent type +- `general` + +### Expected output +- location lesson is understandable and runnable +- preview clearly explains placement/targeting + +### Validation +- starter code renders content in named surfaces +- content appears in the correct visual slot after edits + +## Batch L — Polish and verify + +### Goal +Improve readability and remove obvious prototype blockers. + +### Includes +- 12.1 Add lesson progress affordance +- 12.2 Improve shell spacing and typography +- 12.3 Improve button labels and helper text +- 12.4 Improve preview empty/error states +- 12.5 Add minimal branding alignment +- 13.1 Start dev app and verify boot +- 13.2 Verify lesson switching +- 13.3 Verify notifications lesson manually +- 13.4 Verify menu items lesson manually +- 13.5 Verify locations lesson manually +- 13.6 Verify responsive layout manually +- 13.7 Fix any obvious prototype regressions + +### Suggested agent type +- `general` for implementation and verification +- `browser-operator` later if a browser review pass is requested + +### Expected output +- prototype is coherent and demoable +- major teaching flows work without obvious breakage + +### Validation +- all three lessons work end-to-end +- layout is understandable on desktop and narrow screens + +--- + +## Recommended Execution Order + +Run batches in this order: + +1. Batch A — Scaffold the package +2. Batch B — Build the split tutorial shell +3. Batch C — Add lesson data and navigation +4. Batch D — Add the first editor experience +5. Batch E — Add preview shell and dummy admin skeleton +6. Batch F — Add runtime state plumbing +7. Batch G — Implement the mock Admin SDK bridge +8. Batch H — Add code execution flow +9. Batch I — Finish the notifications lesson +10. Batch J — Finish the menu items lesson +11. Batch K — Finish the locations / positions lesson +12. Batch L — Polish and verify + +## Parallelization Notes + +Most batches should remain sequential because they build on shared app structure. + +Limited safe parallelism: + +- Batch C can begin once Batch B has stable component boundaries +- Batch D and Batch E can partially proceed in parallel after Batch B if interfaces are agreed up front +- Lesson copy work inside Batches I/J/K can be parallelized after runtime and execution foundations are complete + +Avoid parallelizing: + +- runtime-state and bridge changes across multiple agents at the same time +- overlapping edits to `App.vue` and shared shell composition without explicit coordination + +## Handoff Guidance for Subagents + +Each delegated batch should include: + +- the brief in `.orchestrator/implementation-brief.md` +- this plan file +- the exact batch name and included tasks +- a reminder to stay within prototype scope +- a request to summarize changed files, assumptions, and follow-up risks diff --git a/.orchestrator/next-pass-recommendation.md b/.orchestrator/next-pass-recommendation.md new file mode 100644 index 000000000..50a8d6ae3 --- /dev/null +++ b/.orchestrator/next-pass-recommendation.md @@ -0,0 +1,97 @@ +# Admin SDK Tutorial Prototype — Recommended Next Pass + +## Recommendation + +The best next implementation pass is: + +## 1. Upgrade the editor experience + +### Why + +The current prototype already proves: + +- the split tutorial layout works +- the lesson loop works +- the dummy admin teaching model works +- in-browser execution is understandable enough for a prototype + +The weakest remaining part of the experience is now the editor. + +The textarea is sufficient for proving the concept, but it is now the main thing making the tutorial feel less product-ready. + +### Recommended scope + +- replace the textarea with a real editor component +- add syntax highlighting for TypeScript/JavaScript +- preserve the simple single-file model +- do **not** add multi-file editing yet +- do **not** add heavy IDE/platform behavior yet + +### Good outcome for this pass + +- the tutorial feels more trustworthy and enjoyable to edit in +- learner code is easier to scan +- the overall prototype feels much closer to a real interactive tutorial + +--- + +## 2. Add lightweight lesson validation after the editor upgrade + +### Why + +Once the editor feels credible, the next biggest product improvement is helping the learner know when they succeeded. + +### Recommended scope + +- add simple per-lesson validation +- define success checks for the three existing lessons +- show a lightweight solved/unsolved state +- optionally add a “Check” or “Solve” affordance if needed + +### Example validation targets + +- **Notifications:** title/message/tone changed and preview updated +- **Menu items:** dynamic item exists with expected label/position +- **Locations:** content rendered into the expected slot + +--- + +## 3. Reassess execution safety after validation is in place + +### Why + +The current execution approach is acceptable for a prototype, but if the tutorial becomes more widely used internally or externally, the execution model should become more constrained. + +### Recommended scope + +- keep the current execution model for now if iteration speed is still the priority +- plan a safer constrained execution layer once editor + validation are stable + +--- + +## Concepts to add after that + +After editor + validation, the next Admin SDK concepts to consider are: + +- action buttons +- context / payload access +- modals or overlays +- basic communication/event flows + +--- + +## Packaging / integration direction + +For now, keeping this work in: + +`packages/admin-sdk-tutorial` + +is still reasonable while the interaction model evolves. + +Once the concept is validated, the next product decision should be whether this remains a standalone package app or becomes part of the Admin SDK documentation experience. + +--- + +## Final recommendation in one sentence + +**Next, replace the textarea with a real code editor, then add lightweight per-lesson validation before investing in a safer execution model or broader lesson coverage.** diff --git a/.orchestrator/real-sdk-integration-plan.md b/.orchestrator/real-sdk-integration-plan.md new file mode 100644 index 000000000..eec63c2ce --- /dev/null +++ b/.orchestrator/real-sdk-integration-plan.md @@ -0,0 +1,743 @@ +# Admin SDK Tutorial Prototype — Real SDK + Dummy Host Integration Plan + +## Goal + +Replace the current fake bridge approach with an architecture where: + +- learner code runs inside a lesson iframe +- learner code imports and uses the **real** `@shopware-ag/meteor-admin-sdk` package +- the dummy admin shell acts as a **host application** +- the host catches and handles the SDK's real `postMessage` traffic +- the preview stays visually simplified, but the runtime flow is close to the real Shopware Admin SDK model + +This means the browser tutorial should no longer teach fake APIs like: + +- `sdk.menu.add(...)` +- `sdk.location.render(...)` + +Instead, it should execute real Admin SDK code and respond to real message types. + +--- + +## Clarified direction + +Confirmed requirements for this plan: + +- real SDK code should execute **inside the lesson iframe** +- the dummy admin host should be **close to the real postMessage flow** +- first end-to-end concepts should be: + - notifications + - menu items + - locations / positions +- learner code should use **real imports** from the Admin SDK package +- locations should use **real host concepts with simplified visuals** +- this plan should be based on actual SDK internals/docs, not just API renaming + +--- + +## What the real SDK does + +## 1. Connection model + +The SDK initializes its messaging channel on load and sends a `__registerWindow__` message to the parent. + +The host is expected to register the iframe window and origin in the source registry. + +Important implication: + +- we should not simulate an invented runtime protocol +- we should let the real SDK boot and talk to a real parent host window + +## 2. Transport model + +The real SDK uses: + +- `window.postMessage` +- JSON string payloads +- `_type`, `_data`, `_callbackId` request envelopes +- `_type`, `_response`, `_callbackId` response envelopes + +It also supports serialized function callbacks via internal `__function__` transport. + +Important implication: + +- host-side message handling should preferably use the SDK's own channel helpers instead of custom ad hoc parsing + +## 3. Real concepts we need to support + +### Notifications + +Real concept: + +- `notification.dispatch(...)` + +### Menu items + +Real concept: + +- `ui.menu.addMenuItem(...)` + +### Locations / positions + +Real concept is more architectural: + +- host UI is extended at a `positionId` +- content/view routing is based on `locationId` +- the extension decides what to render using `location.is(...)` +- host may react to `locationUpdateHeight` / `locationUpdateUrl` + +Important implication: + +- locations should not be modeled as a single fake `render(...)` call +- the tutorial needs a host shell that owns surfaces and iframes/iframe-like views per location + +--- + +## Proposed target architecture + +## A. Parent app = tutorial shell + dummy admin host + +The parent app should own: + +- the lesson UI +- the code editor +- the preview frame chrome +- the dummy admin host state +- the host-side Admin SDK handlers + +The parent should also host one or more iframes that represent extension runtime contexts. + +## B. Lesson iframe = real extension runtime + +The learner code should run inside an iframe that: + +- imports the real `@shopware-ag/meteor-admin-sdk` +- executes real SDK calls +- talks to the parent using the SDK's real channel implementation + +This iframe should receive a URL containing the correct `location-id` query parameter so real location APIs work. + +## C. Dummy admin host = real handler layer + simplified UI + +The dummy host should register handlers for the real message types and update simplified host UI state. + +Recommended implementation: + +- use the SDK's channel handling utilities from the package +- do not hand-roll a fake message system unless absolutely necessary + +--- + +## Implementation phases + +## Phase 1 — Build a real iframe runtime container + +### Goal +Create a lesson runtime iframe that can execute real Admin SDK code. + +### Tasks +- create a dedicated iframe runtime entry in `packages/admin-sdk-tutorial` +- load the runtime in an iframe from the parent preview +- make the iframe accept lesson code input +- make the iframe execute lesson code with real imports from `@shopware-ag/meteor-admin-sdk` +- include the right `location-id` in the iframe URL + +### Expected result +- learner code runs in a real iframe context +- real Admin SDK package loads there +- the parent sees real SDK postMessages + +### Tiny executable tasks + +#### 1.1 Create iframe runtime directory +- add `src/iframe-runtime/` structure +- create placeholder entry files + +#### 1.2 Add iframe runtime app entry +- create a minimal iframe runtime bootstrap file +- ensure it can mount independently from the parent app + +#### 1.3 Add iframe HTML route/entry strategy +- decide whether the iframe uses a separate html entry or routed app entry +- wire Vite accordingly + +#### 1.4 Render a minimal iframe shell +- show a simple mounted runtime placeholder in the iframe + +#### 1.5 Mount iframe inside preview panel +- render a real iframe in the preview area +- confirm parent and iframe both load successfully + +#### 1.6 Pass starter code into iframe +- define a parent-to-iframe code handoff mechanism +- keep it simple for the first pass + +#### 1.7 Add location-id query param to iframe URL +- include a configurable `location-id` in iframe src + +#### 1.8 Verify iframe receives URL params correctly +- confirm runtime can read the expected `location-id` + +#### 1.9 Add real SDK import to iframe bootstrap +- import the real admin-sdk package in the iframe runtime +- confirm it loads without crashing + +#### 1.10 Verify parent sees first SDK postMessage +- confirm the real SDK posts to the parent window + +--- + +## Phase 2 — Build host-side source registration and channel handling + +### Goal +Make the dummy host behave like a real parent host for the SDK channel. + +### Tasks +- inspect/use the SDK channel helpers from the real package +- support `__registerWindow__` handling and source registration +- ensure iframe window + origin are stored correctly for replies +- validate origin/source safely in the tutorial host +- keep the host-side messaging logic isolated in a dedicated runtime module + +### Expected result +- iframe and parent are connected through the real SDK handshake +- host can answer real SDK requests + +### Tiny executable tasks + +#### 2.1 Create host runtime directory +- add `src/host/` structure for parent-side SDK runtime logic + +#### 2.2 Add host bootstrap module +- centralize host runtime startup in one module + +#### 2.3 Inspect usable SDK channel imports +- confirm exact import path(s) to use from the real package for host-side helpers + +#### 2.4 Register minimal message listener in parent +- add a non-invasive message observer for debugging/verification + +#### 2.5 Implement `__registerWindow__` handling +- catch the initial SDK registration message + +#### 2.6 Store iframe window reference safely +- track iframe window/source in host runtime state + +#### 2.7 Store origin/referrer metadata safely +- keep enough origin information for replies and validation + +#### 2.8 Add source validation guardrails +- reject clearly invalid/unexpected sources + +#### 2.9 Move message logic out of components +- keep handler setup in host runtime modules, not Vue component bodies + +#### 2.10 Verify request-response flow with one trivial handler +- confirm the parent can answer a real SDK-originated request + +--- + +## Phase 3 — Implement real notification handling + +### Goal +Support real `notification.dispatch(...)` from iframe code. + +### Tasks +- replace lesson code with real notification imports and calls +- implement host handler for notification dispatch message type +- map the real payload shape into dummy host notification UI +- support at least title/message/variant +- optionally support callback actions only if the handler path is stable enough + +### Expected result +- learner writes real notification SDK code +- dummy host shows a notification based on real SDK messaging + +### Tiny executable tasks + +#### 3.1 Replace notifications starter code with real imports +- update lesson code to import the real notification API + +#### 3.2 Replace fake notification payload fields +- switch from fake fields like `tone` to real SDK fields like `variant` + +#### 3.3 Add notification execution path in iframe +- ensure lesson code runs successfully from the iframe runtime + +#### 3.4 Register host notification handler +- implement handling for the real notification message type + +#### 3.5 Map notification payload into host state +- update dummy host state from real payload values + +#### 3.6 Render real notification result in preview +- show the resulting notification in the dummy host UI + +#### 3.7 Verify end-to-end notification flow +- run real lesson code and confirm host updates from postMessage + +#### 3.8 Verify error handling for notification lesson +- confirm invalid code still fails gracefully + +--- + +## Phase 4 — Implement real menu item handling + +### Goal +Support real `ui.menu.addMenuItem(...)` from iframe code. + +### Tasks +- replace lesson code with real menu API imports/calls +- implement host handler for the real menu item add message type +- store host-side menu items in dummy admin state +- render those items in the sidebar +- on click, open or route to the related `locationId` + +### Expected result +- learner writes real menu SDK code +- dummy host sidebar updates from real SDK messaging + +### Tiny executable tasks + +#### 4.1 Replace menu lesson starter code with real imports +- update lesson code to import real menu APIs + +#### 4.2 Use real `ui.menu.addMenuItem(...)` lesson code +- remove the fake menu call from the learner-facing lesson + +#### 4.3 Add menu message handler in host runtime +- implement handling for the real menu item add message type + +#### 4.4 Persist dynamic menu items in host state +- store host-side menu items from real SDK requests + +#### 4.5 Render dynamic menu items in sidebar +- reflect real handler output in dummy admin navigation + +#### 4.6 Add click handling for menu items +- let sidebar clicks switch/open the related location view + +#### 4.7 Wire menu item locationId into iframe selection +- update active iframe/location based on menu interaction + +#### 4.8 Verify end-to-end menu flow +- confirm real SDK lesson code updates host navigation correctly + +--- + +## Phase 5 — Implement real location/position flow + +### Goal +Teach real location and position concepts, even with simplified visuals. + +### Tasks +- rewrite the lesson around real concepts: + - `positionId` + - `locationId` + - `location.is(...)` +- add host-owned extension surfaces/cards labeled by position +- create location-specific iframe views using query params like `?location-id=...` +- support host handling for `locationUpdateHeight` +- optionally support `locationUpdateUrl` if useful for the tutorial flow + +### Expected result +- learner code uses real location concepts +- dummy host visualizes where extension views belong +- the extension iframe can determine its current location using the real SDK API + +### Tiny executable tasks + +#### 5.1 Rewrite lesson copy around real location concepts +- update copy to teach `positionId`, `locationId`, and `location.is(...)` + +#### 5.2 Rewrite locations starter code with real imports +- remove fake render-style lesson code + +#### 5.3 Add host-owned position surfaces +- render labeled host surfaces/cards for simplified positions + +#### 5.4 Add location-specific iframe URL generation +- build iframe URLs with the right `location-id` + +#### 5.5 Add support for switching visible location view +- allow the parent host to show the correct runtime view for a location + +#### 5.6 Implement `locationUpdateHeight` handler +- resize iframe or tracked host view height from real SDK messages + +#### 5.7 Decide whether to support `locationUpdateUrl` now +- explicitly choose keep/skip for this first pass + +#### 5.8 If included, implement `locationUpdateUrl` handler +- store/update route state safely in the dummy host + +#### 5.9 Verify `location.is(...)` behavior in iframe +- confirm the lesson runtime sees the expected location from URL params + +#### 5.10 Verify end-to-end locations flow +- confirm real lesson code updates the correct host surface + +--- + +## Phase 6 — Replace mock bridge lesson execution path + +### Goal +Remove the current fake bridge from the core lesson path. + +### Tasks +- stop using the mock bridge for the three primary lessons +- route Run/Reset through the iframe runtime instead +- keep the old mock code only temporarily if needed during migration +- remove deprecated fake lesson APIs after the real path is stable + +### Expected result +- the prototype is primarily powered by the real SDK package +- the dummy admin shell acts as a real host adapter, not a fake API simulator + +### Tiny executable tasks + +#### 6.1 Identify current fake bridge dependencies +- list which components/modules still depend on the mock bridge + +#### 6.2 Route Run through iframe execution +- make Run use the iframe runtime instead of the mock bridge path + +#### 6.3 Route Reset through iframe runtime +- make Reset restore lesson state via the iframe path + +#### 6.4 Keep temporary compatibility layer only where needed +- isolate any remaining bridge code behind a temporary adapter + +#### 6.5 Remove fake notifications path +- stop using the old mock notification behavior for the main lesson flow + +#### 6.6 Remove fake menu path +- stop using the old mock menu behavior for the main lesson flow + +#### 6.7 Remove fake locations path +- stop using the old mock location behavior for the main lesson flow + +#### 6.8 Delete deprecated bridge code once unused +- remove dead mock runtime pieces after migration is stable + +--- + +## Phase 7 — Validate parity and teaching clarity + +### Goal +Ensure the new architecture is both correct and understandable. + +### Tasks +- verify notification lesson end-to-end in browser +- verify menu lesson end-to-end in browser +- verify location lesson end-to-end in browser +- confirm postMessage flow is working as expected +- check console/network/runtime logs for handler issues +- simplify copy where real SDK complexity becomes too noisy + +### Expected result +- prototype still feels approachable +- but now teaches real SDK behavior and terminology + +### Tiny executable tasks + +#### 7.1 Browser-verify notifications lesson +- test the real notification lesson end-to-end + +#### 7.2 Browser-verify menu lesson +- test the real menu lesson end-to-end + +#### 7.3 Browser-verify locations lesson +- test the real locations lesson end-to-end + +#### 7.4 Check message traffic sanity +- confirm request/response flow behaves as expected in browser/devtools + +#### 7.5 Check console for handler/runtime issues +- identify any host or iframe runtime warnings/errors + +#### 7.6 Check iframe sizing behavior +- verify height updates behave reasonably in the dummy host + +#### 7.7 Tighten teaching copy where needed +- simplify any lesson text that became too implementation-heavy + +#### 7.8 Final browser sanity pass +- confirm the prototype still feels coherent and teachable + +--- + +## Required host-side capabilities + +The dummy host should be prepared to handle at least: + +- `__registerWindow__` +- notification dispatch message(s) +- menu item add message(s) +- location-related update messages such as height updates + +Potentially useful additional support later: + +- callback transport for action buttons +- URL update handling +- more UI extension APIs + +--- + +## Recommended implementation modules + +Suggested new areas inside `packages/admin-sdk-tutorial`: + +- `src/host/` + - source registry / host bootstrap + - channel handler registration + - host state adapters +- `src/iframe-runtime/` + - iframe app entry + - lesson runtime bootstrap + - real SDK execution wrapper +- `src/lessons/` + - updated lesson code using real SDK imports +- `src/preview/` + - dummy host surfaces / location frame rendering + +--- + +## Constraints and gotchas + +- the real SDK depends on parent/iframe messaging assumptions, so the iframe runtime must be a genuine iframe +- function callbacks require correct SDK serializer/deserializer support; avoid custom raw message handling if possible +- `location.is(...)` depends on URL query parameters, so iframe URLs must be managed deliberately +- the tutorial host should still validate message source/origin even in local prototype mode +- a hidden bootstrap location such as `sw-main-hidden` may be useful for registration-style lesson flows + +--- + +## Migration strategy + +Recommended order: + +1. notifications +2. menu items +3. locations / positions + +Reason: + +- notifications are the smallest end-to-end real handler slice +- menu adds real host navigation behavior with manageable complexity +- locations require the deepest conceptual and architectural change + +--- + +## Suggested execution batches + +These tiny tasks can be grouped into practical implementation batches. + +### Batch A — Real iframe runtime bootstrap +- 1.1 through 1.10 + +### Batch B — Host registration and channel setup +- 2.1 through 2.10 + +### Batch C — Real notifications vertical slice +- 3.1 through 3.8 + +### Batch D — Real menu vertical slice +- 4.1 through 4.8 + +### Batch E — Real locations vertical slice +- 5.1 through 5.10 + +### Batch F — Remove fake bridge path +- 6.1 through 6.8 + +### Batch G — End-to-end validation and polish +- 7.1 through 7.8 + +--- + +## Source-of-truth references + +### Core internals +- `packages/admin-sdk/src/channel.ts` +- `packages/admin-sdk/src/message-types.ts` +- `packages/admin-sdk/src/_internals/serializer/function-serializer.ts` + +### Feature APIs +- `packages/admin-sdk/src/notification/index.ts` +- `packages/admin-sdk/src/ui/menu/index.ts` +- `packages/admin-sdk/src/location/index.ts` +- `packages/admin-sdk/src/ui/component-section/index.ts` +- `packages/admin-sdk/src/ui/tabs/index.ts` + +### Docs +- `docs/admin-sdk/internals/how-it-works.md` +- `docs/admin-sdk/api-reference/notification.md` +- `docs/admin-sdk/api-reference/ui/menu.md` +- `docs/admin-sdk/api-reference/location.md` +- `docs/admin-sdk/api-reference/ui/component-section.md` +- `docs/admin-sdk/api-reference/ui/tabs.md` +- `docs/admin-sdk/concepts/locations.md` +- `docs/admin-sdk/concepts/component-sections.md` +- `docs/admin-sdk/concepts/positions.md` + +--- + +## Recommendation + +The correct next direction is: + +- **do not just rename the fake bridge APIs** +- **do use the real Admin SDK package inside a lesson iframe** +- **do implement real host-side handlers in the dummy admin shell** +- **keep the visuals simplified, but make the runtime architecture real** + +--- + +## Current implementation status + +### Finished batches + +#### Batch A — Real iframe runtime bootstrap +Status: **finished** + +Completed: +- real iframe runtime entry exists +- iframe loads inside the preview +- real `@shopware-ag/meteor-admin-sdk` is imported in the iframe runtime +- lesson code is sent from parent to iframe +- parent observes real SDK traffic +- `__registerWindow__` is acknowledged so bootstrap does not time out + +#### Batch B — Host registration and channel setup +Status: **finished** + +Completed: +- parent-side host runtime module exists +- host-side message observation was moved out of the component body +- source registration count is surfaced in the UI +- real channel bootstrap is stable in browser + +#### Batch C — Real notifications vertical slice +Status: **finished** + +Completed: +- notifications lesson now uses the real API shape +- real notification traffic flows from iframe to host +- dummy host updates notification UI from real handler results +- success/error states work +- last successful notification state is preserved on error + +#### Batch D — Real menu vertical slice +Status: **finished** + +Completed: +- menu lesson now uses the real API shape: `ui.menu.addMenuItem(...)` +- real `menuItemAdd` traffic is sent from iframe to host +- menu success/error states work +- no obvious console issues + +Completed: +- edited menu payloads now update the dummy host sidebar correctly +- dynamic menu item ordering reacts to changed position values +- menu success/error states are preserved through the real iframe/host path + +Minor remaining note: +- the iframe runtime display can still show concatenated old + new code text during repeated runs, but host behavior is now correct + +#### Batch E — Real locations vertical slice +Status: **finished** + +Completed: +- locations lesson now uses real concepts: + - `location.MAIN_HIDDEN` + - `ui.componentSection.add(...)` + - `location.is(...)` + - `location.updateHeight(...)` +- real `uiComponentSectionRenderer` traffic flows from iframe to host +- dummy host renders location iframes inside the chosen host slot +- host slot changes correctly when `positionId` changes +- height updates are handled via real `locationUpdateHeight` traffic +- success/error states work through the real iframe/host path + +#### Batch F — Remove fake bridge path +Status: **finished** + +Completed: +- old fake bridge execution path was removed from the active lesson flow +- old fake runtime executor was removed +- all three lessons now work through the real iframe + host message flow +- verification confirmed no visible dependency on the old mock bridge remains + +--- + +## What is currently broken + +### Main broken area + +There is currently **no blocking migration issue** in Batches A-F. + +The remaining work is now primarily **polish and cleanup**, not a core runtime blocker. + +### Remaining rough edges + +- the iframe runtime display can still show concatenated old + new code text during repeated runs +- some error output can still feel slightly repetitive depending on the lesson +- code and runtime synchronization should still be simplified and cleaned up before final polish/commit + +### Likely cleanup area + +The remaining issue appears to be mostly in the **iframe runtime display/synchronization layer**, not in the real host handler flow. + +--- + +## Follow-up task breakdown for cleanup and validation + +### Task group 1 — Clean up iframe runtime display behavior + +#### 1.1 Reproduce concatenated iframe code display deterministically +- confirm the exact circumstances where old + new code are both shown + +#### 1.2 Compare editor value vs iframe displayed value +- confirm whether the iframe is receiving the same code shown in the editor + +#### 1.3 Compare iframe displayed value vs executed value +- confirm whether the code displayed in the iframe is the code actually being executed + +#### 1.4 Simplify runtime code display source +- make the iframe display only the current run snapshot or current editor state, not both ambiguously + +### Task group 2 — Polish error/output messaging + +#### 2.1 Reduce repeated failure wording +- simplify output cards so one failure message is enough + +#### 2.2 Align failure copy across all three lessons +- ensure notifications, menu, and locations all use equally clear output wording + +#### 2.3 Verify preserved-success-state behavior still reads clearly +- make sure preserved host state on error feels intentional, not confusing + +### Task group 3 — Final validation / polish + +#### 3.1 Re-run notifications lesson end-to-end +#### 3.2 Re-run menu lesson end-to-end +#### 3.3 Re-run locations lesson end-to-end +#### 3.4 Verify desktop layout still feels coherent +#### 3.5 Verify mobile layout still feels coherent + +### Task group 4 — Prepare final commit/summary + +#### 4.1 Summarize runtime architecture as implemented +#### 4.2 Note remaining known quirks explicitly +#### 4.3 Prepare clean commit once Batch G is complete + +--- + +## Resume point + +When implementation resumes, the next focus should be: + +1. finish Batch G validation/polish +2. clean up remaining minor iframe-display quirks if worthwhile +3. prepare a clean summary + commit diff --git a/.orchestrator/second-pass-plan.md b/.orchestrator/second-pass-plan.md new file mode 100644 index 000000000..4deb8d0b5 --- /dev/null +++ b/.orchestrator/second-pass-plan.md @@ -0,0 +1,351 @@ +# Admin SDK Tutorial Prototype — Second Pass Plan + +## Goal + +Run a focused second pass on the prototype to improve: + +- visual quality +- teaching clarity +- interaction polish +- readiness for a richer editor/execution phase later + +This pass should still stay within prototype scope. It should not become a full platform rebuild. + +--- + +## Phase 1 — Refine the teaching experience + +### Goal +Make each lesson easier to understand at a glance. + +### Tasks +- reduce duplicated information between preview, output, and empty states +- make the primary lesson task more prominent +- improve wording for lesson descriptions and objectives +- make success/error states feel more intentional + +### Output +- clearer lesson framing +- less noisy preview state +- stronger “what should I do now?” guidance + +### Tiny executable tasks + +#### 1.1 Inventory duplicated lesson information +- note repeated information across sidebar, preview, toast, and output +- identify what should remain primary vs secondary + +#### 1.2 Make the current task more prominent +- highlight the active lesson objective more clearly +- ensure it is visible without scanning multiple panels + +#### 1.3 Tighten notifications lesson description +- shorten or clarify the description text +- make the expected learner action explicit + +#### 1.4 Tighten menu lesson description +- shorten or clarify the description text +- make the expected learner action explicit + +#### 1.5 Tighten locations lesson description +- shorten or clarify the description text +- make the expected learner action explicit + +#### 1.6 Improve lesson objective wording +- standardize objective phrasing across all lessons +- keep objectives action-oriented + +#### 1.7 Improve output success message copy +- replace generic success text with more lesson-aware feedback + +#### 1.8 Improve output error message copy +- make failure messaging feel more intentional and useful + +#### 1.9 Reduce repeated preview copy +- remove or simplify duplicated text in empty state / toast / output where possible + +#### 1.10 Verify all three lessons still read clearly +- manually review lesson copy coherence after edits + +--- + +## Phase 2 — Improve the visual shell + +### Goal +Make the tutorial feel more polished and cohesive. + +### Tasks +- refine sidebar spacing, hierarchy, and progress treatment +- improve editor/preview balance and panel styling +- tighten typography and spacing across the shell +- improve badge, label, and card semantics +- make the dummy admin feel more deliberate and less placeholder-like + +### Output +- more convincing split-layout tutorial UI +- better scanability +- stronger visual rhythm + +### Tiny executable tasks + +#### 2.1 Refine sidebar spacing +- adjust gaps, padding, and section spacing in the left column + +#### 2.2 Improve sidebar hierarchy +- strengthen distinctions between title, description, progress, and task sections + +#### 2.3 Improve progress treatment +- refine the step count / progress presentation + +#### 2.4 Improve lesson card states +- make active/inactive lesson items feel clearer + +#### 2.5 Refine workspace panel spacing +- balance internal padding and gaps across editor/preview/output panels + +#### 2.6 Improve panel headers +- align label, title, actions, and metadata more cleanly + +#### 2.7 Tighten editor/preview proportions +- slightly adjust layout balance if one side feels too heavy + +#### 2.8 Refine typography scale +- improve consistency of heading/body/label sizes + +#### 2.9 Improve semantic badge styling +- refine status chips, labels, and small badges + +#### 2.10 Verify desktop shell coherence +- confirm the full split layout feels visually consistent + +--- + +## Phase 3 — Upgrade the dummy admin model + +### Goal +Make the preview better at teaching Admin SDK concepts. + +### Tasks +- improve notification presentation so it feels closer to a teaching toast +- improve dynamic sidebar/menu item treatment +- improve extension slot cards and location labels +- clarify host-vs-extension mental model where useful + +### Output +- notifications look more intentional +- menu additions are easier to read +- locations/positions are even more understandable + +### Tiny executable tasks + +#### 3.1 Refine notification container layout +- improve internal spacing and hierarchy of the toast-like UI + +#### 3.2 Improve notification tone styling +- make info/success states more distinct but still minimal + +#### 3.3 Improve dynamic menu item readability +- refine spacing between label and “new” marker + +#### 3.4 Improve menu item semantics +- make dynamic items feel intentionally added, not just appended text + +#### 3.5 Refine extension slot labels +- improve wording/formatting of slot labels and titles + +#### 3.6 Improve injected content treatment +- make injected content visually distinct from the host slot container + +#### 3.7 Clarify host surface mental model +- make it clearer which UI belongs to the host vs extension slot + +#### 3.8 Verify each concept is visually obvious +- check notification/menu/location concepts one by one in the preview + +--- + +## Phase 4 — Improve interaction polish + +### Goal +Make run/reset/output flows feel cleaner and more trustworthy. + +### Tasks +- decide whether Reset should also re-run automatically +- improve output messaging for success/error/reset states +- make run feedback feel immediate +- add small interaction affordances where useful + +### Output +- fewer confusing states +- smoother teaching loop +- more coherent execution feedback + +### Tiny executable tasks + +#### 4.1 Decide Reset behavior +- choose whether Reset should only restore code or also auto-run + +#### 4.2 Implement chosen Reset behavior +- update reset flow accordingly + +#### 4.3 Improve run success feedback +- make success feedback more immediate and less generic + +#### 4.4 Improve reset feedback +- make reset state understandable without reading too much text + +#### 4.5 Improve error feedback presentation +- clarify placement and styling of execution errors + +#### 4.6 Add subtle run-state affordance +- add a small UI signal that a run occurred if useful + +#### 4.7 Review control labels +- ensure Run/Reset labels still feel correct after behavior changes + +#### 4.8 Verify the execution loop feels coherent +- manually test edit → run → reset → run again + +--- + +## Phase 5 — Browser review and iteration + +### Goal +Validate the second pass visually in a real browser and tighten obvious issues. + +### Tasks +- verify desktop layout +- verify narrow/mobile layout +- compare lesson flows side-by-side +- fix obvious spacing, overflow, and clarity issues + +### Output +- a more demo-ready prototype +- fewer visual rough edges + +### Tiny executable tasks + +#### 5.1 Desktop browser check +- review the prototype on desktop viewport + +#### 5.2 Mobile browser check +- review the prototype on narrow/mobile viewport + +#### 5.3 Verify notifications flow visually +- run through the full notifications lesson in-browser + +#### 5.4 Verify menu flow visually +- run through the full menu lesson in-browser + +#### 5.5 Verify locations flow visually +- run through the full locations lesson in-browser + +#### 5.6 Note layout issues +- capture spacing, overflow, and hierarchy issues found in browser + +#### 5.7 Fix first browser issue +- resolve the highest-priority UI issue found + +#### 5.8 Re-check in browser +- verify that the first fix worked + +#### 5.9 Fix second browser issue if needed +- resolve one more obvious issue only if it materially improves the prototype + +#### 5.10 Final browser pass +- confirm the prototype feels demo-ready enough for the second pass goal + +--- + +## Phase 6 — Optional follow-up after the second pass + +These should happen only after the visual/product pass feels strong enough. + +### Candidate next steps +- replace textarea with a real code editor +- add lesson validation / “Solve” states +- move to a safer execution model +- add more Admin SDK concepts +- define documentation integration path + +### Tiny executable planning tasks + +#### 6.1 Decide whether editor upgrade is next +- assess if textarea is blocking further prototype learning value + +#### 6.2 Define editor upgrade scope +- decide whether syntax highlighting alone is enough or if a fuller editor is needed + +#### 6.3 Define lesson validation scope +- outline what “success” means for each current lesson + +#### 6.4 Reassess execution safety needs +- decide whether current execution approach is still acceptable for prototype use + +#### 6.5 Identify next Admin SDK concepts +- shortlist the next most valuable concepts after the first three lessons + +#### 6.6 Decide docs integration direction +- outline whether this should remain a package app or connect into docs later + +#### 6.7 Write recommendation for next implementation pass +- summarize the best next technical/product step after the second pass + +--- + +## Recommended execution order + +1. Phase 1 — Refine the teaching experience +2. Phase 2 — Improve the visual shell +3. Phase 3 — Upgrade the dummy admin model +4. Phase 4 — Improve interaction polish +5. Phase 5 — Browser review and iteration +6. Phase 6 — Optional follow-up + +--- + +## Suggested second-pass execution batches + +These tiny tasks can be grouped into small execution batches. + +### Batch A — Lesson clarity +- 1.1 through 1.6 + +### Batch B — Feedback copy and repetition cleanup +- 1.7 through 1.10 + +### Batch C — Sidebar and shell polish +- 2.1 through 2.5 + +### Batch D — Typography, badges, and layout refinement +- 2.6 through 2.10 + +### Batch E — Notification and menu preview polish +- 3.1 through 3.4 + +### Batch F — Locations preview polish +- 3.5 through 3.8 + +### Batch G — Interaction polish +- 4.1 through 4.8 + +### Batch H — Browser review and iteration +- 5.1 through 5.10 + +### Batch I — Decide next implementation pass +- 6.1 through 6.7 + +--- + +## Scope guardrails + +During this second pass: + +- do not introduce a full authoring system +- do not introduce persistence or backend services +- do not overbuild the execution environment +- do not optimize for production parity yet + +The main question for this pass is: + +**Does the prototype now feel compelling enough that it is clearly worth evolving further?** diff --git a/packages/admin-sdk-tutorial/.gitignore b/packages/admin-sdk-tutorial/.gitignore new file mode 100644 index 000000000..f06235c46 --- /dev/null +++ b/packages/admin-sdk-tutorial/.gitignore @@ -0,0 +1,2 @@ +node_modules +dist diff --git a/packages/admin-sdk-tutorial/dummy-admin-shell.html b/packages/admin-sdk-tutorial/dummy-admin-shell.html new file mode 100644 index 000000000..5a8383d1d --- /dev/null +++ b/packages/admin-sdk-tutorial/dummy-admin-shell.html @@ -0,0 +1,12 @@ + + + + + + Admin SDK Tutorial Dummy Admin Shell + + +
+ + + diff --git a/packages/admin-sdk-tutorial/env.d.ts b/packages/admin-sdk-tutorial/env.d.ts new file mode 100644 index 000000000..11f02fe2a --- /dev/null +++ b/packages/admin-sdk-tutorial/env.d.ts @@ -0,0 +1 @@ +/// diff --git a/packages/admin-sdk-tutorial/iframe-runtime.html b/packages/admin-sdk-tutorial/iframe-runtime.html new file mode 100644 index 000000000..443649c6e --- /dev/null +++ b/packages/admin-sdk-tutorial/iframe-runtime.html @@ -0,0 +1,12 @@ + + + + + + Admin SDK Tutorial Runtime + + +
+ + + diff --git a/packages/admin-sdk-tutorial/index.html b/packages/admin-sdk-tutorial/index.html new file mode 100644 index 000000000..1b153bf42 --- /dev/null +++ b/packages/admin-sdk-tutorial/index.html @@ -0,0 +1,13 @@ + + + + + + + Meteor Admin SDK Tutorial Prototype + + +
+ + + diff --git a/packages/admin-sdk-tutorial/package.json b/packages/admin-sdk-tutorial/package.json new file mode 100644 index 000000000..7afb1627d --- /dev/null +++ b/packages/admin-sdk-tutorial/package.json @@ -0,0 +1,32 @@ +{ + "name": "@shopware-ag/meteor-admin-sdk-tutorial", + "version": "0.0.0", + "private": true, + "type": "module", + "scripts": { + "dev": "vite", + "build": "run-p type-check \"build-only {@}\" --", + "build-only": "vite build", + "preview": "vite preview", + "type-check": "vue-tsc --build" + }, + "dependencies": { + "@codemirror/lang-javascript": "^6.2.5", + "@codemirror/theme-one-dark": "^6.1.3", + "@shopware-ag/meteor-admin-sdk": "workspace:*", + "@shopware-ag/meteor-component-library": "workspace:*", + "codemirror": "^6.0.1", + "vue": "^3.5.13", + "vue-codemirror6": "^1.3.8" + }, + "devDependencies": { + "@tsconfig/node22": "^22.0.1", + "@types/node": "^25.5.0", + "@vitejs/plugin-vue": "^6.0.5", + "@vue/tsconfig": "^0.7.0", + "npm-run-all2": "^8.0.4", + "typescript": "~5.8.0", + "vite": "^8.0.0", + "vue-tsc": "^3.2.5" + } +} diff --git a/packages/admin-sdk-tutorial/public/favicon.svg b/packages/admin-sdk-tutorial/public/favicon.svg new file mode 100644 index 000000000..d96eee733 --- /dev/null +++ b/packages/admin-sdk-tutorial/public/favicon.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/packages/admin-sdk-tutorial/src/App.vue b/packages/admin-sdk-tutorial/src/App.vue new file mode 100644 index 000000000..5f1c2638b --- /dev/null +++ b/packages/admin-sdk-tutorial/src/App.vue @@ -0,0 +1,253 @@ + + + + + diff --git a/packages/admin-sdk-tutorial/src/components/.gitkeep b/packages/admin-sdk-tutorial/src/components/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/packages/admin-sdk-tutorial/src/components/CodeEditorPanel.vue b/packages/admin-sdk-tutorial/src/components/CodeEditorPanel.vue new file mode 100644 index 000000000..ff08ab851 --- /dev/null +++ b/packages/admin-sdk-tutorial/src/components/CodeEditorPanel.vue @@ -0,0 +1,271 @@ + + + + + diff --git a/packages/admin-sdk-tutorial/src/components/DummyAdminLocationFrame.vue b/packages/admin-sdk-tutorial/src/components/DummyAdminLocationFrame.vue new file mode 100644 index 000000000..cb15e9d27 --- /dev/null +++ b/packages/admin-sdk-tutorial/src/components/DummyAdminLocationFrame.vue @@ -0,0 +1,59 @@ + + +