diff --git a/.agents/skills/image-generation/SKILL.md b/.agents/skills/image-generation/SKILL.md index 631be0a8f..034bcf72a 100644 --- a/.agents/skills/image-generation/SKILL.md +++ b/.agents/skills/image-generation/SKILL.md @@ -1,14 +1,15 @@ --- name: image-generation -description: Generate image assets through the active iPolloWork Image Studio while preserving structured style, camera, lighting, size, and quality choices. +description: Generate image assets through iPolloWork's image service, whether Image Studio is open or closed. --- # Image generation -Use this Skill when the user wants a new image and Image Studio is active. +Use this Skill for a requested new image or a missing supporting image identified while authoring a PPT, website or video. Image Studio does not need to be open. Plan assets during initial creation/full redesign; preserve narrow edit scopes and explicit no-image requests. Reuse suitable assets first; visual clarity and context are valid reasons to generate, not only absolute necessity. Assess the visual purpose, existing assets and best medium internally; no separate assessment report is required. Keep diagrams editable, treat pure decoration as optional, and never present generated illustrative scenes as real evidence. 1. Preserve the user's subject, composition, text, brand, and format requirements. -2. Put visual style, camera, and lighting into the matching structured Image Studio fields when possible instead of repeating them throughout the prompt. -3. Use the installed provider exposed by Image Studio. Never request, print, or place API keys in a prompt or workspace file. -4. Save generated results as new workspace artifacts and report the exact returned path. -5. Keep the first pass focused. Generate variants only when the user asks for alternatives. +2. Discover `openai-image-generation` using `ipollowork_extension_list_actions`, then call its `status` action. Call status first and check authorization, capabilities and supported parameters. Preserve a model explicitly selected for this task or captured workbench request. If it is unavailable or unsuitable, ask before substituting unless alternatives were already authorized, and continue independent file work. For no explicit model, use a verified suitable user-saved preference or existing automatic-selection policy, or the sole suitable authorized model within the task scope and allowed cost settings. With multiple suitable models and no such preference or policy, ask once for the task before committing any image-dependent page; never silently use `defaultModel` or downgrade to shapes merely to avoid the question. Continue independent text/layout work if useful, mark the asset pending, and do not claim the complete deliverable until the choice is answered or the user declines the image. Reuse the verified selection for compatible assets; recheck when the model, operation, parameters or authorization state changes or a service error requires it. A first-result/defaultModel fallback is not evidence of a saved user preference. Missing authorization or an unqueryable capability must not block the caller or open settings: report the state and continue. Never request keys in chat. Do not invent preferences or budgets. Pass the chosen stable model ID explicitly. Never submit variants outside scope; query or recover uncertain jobs before resubmitting. In this image status response, `defaultModel` is an automatic first-available candidate, not a persisted user preference. For an explicit workbench settings/annotation request, honor its captured selection instructions; do not change the workbench model through UI automation. +3. After resolving the model by this policy, call `image_generate` through `ipollowork_extension_call` with that exact stable `model` ID, the prompt, and optional quality/size. Include style, camera, and lighting requirements in the prompt. +4. Use this server action for ordinary chat requests even when Image Studio is open. UI tool discovery and opening the workbench are unnecessary. Use workbench tools only when the user explicitly requests the current workbench settings or selection. Never request, print, or place API keys in a prompt or workspace file. +5. Save generated results as new workspace artifacts and include a Markdown image link to the exact returned path in the final response. Never claim success until the action returns the saved file. For a composition, place the saved image under its existing assets directory, use a project-relative reference, and verify loading, crop and export compatibility before delivering the composition. Standalone images can be opened in Image Studio from the conversation. +6. Keep the first pass focused. Generate variants only when the user asks for alternatives. diff --git a/.agents/skills/ipollowork-design-studio/SKILL.md b/.agents/skills/ipollowork-design-studio/SKILL.md index cf448a534..1d32b5e17 100644 --- a/.agents/skills/ipollowork-design-studio/SKILL.md +++ b/.agents/skills/ipollowork-design-studio/SKILL.md @@ -7,6 +7,8 @@ description: Create or edit HTML designs inside an active iPolloWork Design Stud Use this Skill only for a design project already owned by the active iPolloWork session. The built-in Design Studio, templates, editor, undo history, and exports exist independently of this Skill. +Before initial/full authoring, call `media/artifact_media_review` phase=plan with the active HTML sourcePath and visual needs; follow references/shared-guidelines.md. Before final delivery call phase=check, resolve pending/missing assets and disclose fallbacks. The host queries capabilities and checks saved-file placement and generation receipts; preview remains required. Do not replace this workflow with a verbal assessment or a self-selected geometric style. + ## Session contract - Treat the active session's injected Design contract and exact editable path as authoritative. @@ -14,6 +16,16 @@ Use this Skill only for a design project already owned by the active iPolloWork - Keep all changes inside the current `design//` project. - Never create a replacement project, start another preview server, or alter iPolloWork application files. +## Required type rules + +Before editing, resolve the category from the session contract and manifest, or infer it from the requested deliverable when no manifest is available. Read this Skill's [references/shared-guidelines.md](references/shared-guidelines.md) and [references/design.md](references/design.md), then only the matching category reference listed there. Resolve these paths relative to the current installed Skill, not a remembered checkout. If a file is missing, check the advertised Skill location once and report the gap; never pretend to have read it. + +Use this sequence for bundled/custom templates, fully custom generation and follow-up edits while preserving the narrower edit scope. Type references own structure, interaction and acceptance checks; shared guidelines and media Skills own asset and model decisions. + +For `category: "slides"`, use `ipollowork-presentations` and its packaged `references/shared-guidelines.md`, `references/slides-ppt.md` and `references/layout.md`, including for HTML decks. Preserve the HTML presentation runtime or native editable PPTX contract as appropriate. + +For `category: "video"`, use `ipollowork-video-studio` and the session's Video surface contract. Do not replace the timed composition with a Design HTML page. + ## Editing rules 1. On the initial brief application, derive the content structure from the brief and treat the installed template's sections and components as reusable visual patterns. Add, remove, reorder, repeat, or recombine them when the content requires it; do not carry inherited sample structure forward by default. @@ -25,6 +37,10 @@ Use this Skill only for a design project already owned by the active iPolloWork If the active session provides stricter instructions, those instructions take precedence. -## Content scope +## Content-led layout adaptation + +Follow the injected template layout contract. Before editing, identify reusable typography, palette, spacing, shapes and artwork in the source; sample section geometry is not fixed. Match each section to its purpose: comparison, steps, evidence, case study or key message. Reuse a fitting pattern, vary its proportions/columns/alignment, or compose a new layout from the same primitives. Keep coherent reading order and responsive behavior across widths; do not reduce every section to the same card grid. + +Respect an explicit request to match the template exactly, fixed-brand regions and selected-element scope. Inspect rendered sections for overflow, excessive density, unjustified repetition and style drift. Recompose dense content rather than shrinking text or deleting facts; do not introduce variety merely for decoration. -Let content determine page count, scene count, and duration. Template sample quantities and timings are not limits, even when an inherited checklist calls them fixed. Apply counts or duration constraints only when explicitly requested by the user. Approximate targets allow reasonable variation; explicit maximums remain strict. Do not omit important content or add filler to fit a template. For narration, pass `targetDurationSeconds` only for a user duration request and synchronize scenes to actual audio duration. +For slides and sites, read `core-v1-index.md` beside `brief.json` first, then only the active type's `core-v1-slides/` or `core-v1-site/` catalog, layout guide and shared contract. The index maps shared content relationships; implementations remain type-specific. PPT keeps its fixed canvas and supported editable markers; websites use responsive flow and semantic interactions. Video uses the Video Studio workflow and its `core-v1-video/` catalog with separate timing and playback constraints. Reuse fitting global or local patterns; new layouts remain valid. Copy only structural fragments and scoped styles, excluding preview hosts, palettes and scripts. Preserve the active template's tokens unless restyling is requested, and verify real content/assets under the type rules. Catalog verification never substitutes for current delivery checks. diff --git a/.agents/skills/ipollowork-design-studio/references/design-app.md b/.agents/skills/ipollowork-design-studio/references/design-app.md new file mode 100644 index 000000000..e086e0f0a --- /dev/null +++ b/.agents/skills/ipollowork-design-studio/references/design-app.md @@ -0,0 +1,24 @@ + + +# Application Interface Rules + +Use for `app`: screens, dashboards and interactive prototypes. Read `design.md` and shared guidelines first. + +## Tasks and structure + +- Identify the main user task, entry state, action and observable outcome. Select screens and states from that flow rather than copying a sample dashboard. +- Reuse navigation, controls, spacing and state language. Do not fill space with invented analytics, customers or activity. +- Choose suitable forms, tables, lists, inspectors and detail views. Marketing sections are not a substitute for a usable application flow. +- Keep the implementation boundary explicit: an HTML prototype may demonstrate local interaction, but does not establish authentication, persistence, payment or remote integration. + +## States and assets + +- Cover normal, loading, empty, invalid, failed and completed states needed by the flow. Keep transitions consistent; success must reflect an actual or clearly labeled simulated outcome. +- Preserve input after validation errors. Explain unavailable actions and protect destructive actions appropriately within the artifact's scope. +- Use labeled inputs, accessible state feedback, keyboard navigation and visible focus. Test menus, dialogs, escape/close and forms; do not rely on hover alone. +- Adapt dense navigation/data to narrow screens through intentional scrolling or alternate views, rather than clipping controls or squeezing labels. +- Follow shared media rules for meaningful product/content visuals. Prefer editable charts for data and consistent icons for navigation; decorative generation remains optional. + +## Acceptance + +Drive the primary flow from entry to outcome, including relevant empty/error/recovery cases. Check representative widths, long labels and realistic data volumes. Verify edit/save claims in the supported runtime. Distinguish prototype behavior from connected services and identify untested states. diff --git a/.agents/skills/ipollowork-design-studio/references/design-article.md b/.agents/skills/ipollowork-design-studio/references/design-article.md new file mode 100644 index 000000000..a22cceae7 --- /dev/null +++ b/.agents/skills/ipollowork-design-studio/references/design-article.md @@ -0,0 +1,23 @@ + + +# Article Rules + +Use for `article`: editorial pages, long-form reading and WeChat articles. Read `design.md` and shared guidelines first. + +## Reading and editorial structure + +- Preserve facts, meaning and the requested voice. Derive title, introduction, sections, quotes and conclusion from content rather than a fixed template structure. +- Prioritize sustained reading: suitable line measure, paragraph rhythm and heading relationships. Check Chinese punctuation, mixed scripts and meaningful line breaks in the final font. +- Avoid turning every paragraph into a decorative card or slide. Use lists, emphasis and pull quotes to clarify; do not duplicate passages merely to fill slots. +- Keep captions, credits, links and sources associated with their passage/image. Never invent bylines, publication dates or attribution. + +## Assets and destination + +- Apply shared media rules to useful cover, setting, subject and supporting illustrations. Atmosphere is a valid purpose; there is no image quota. +- Preserve fixed brand header/footer images and nodes marked `data-ipw-fixed="true"`. Targeted text editing does not authorize changing locked elements. +- Distinguish browser articles from publishing-platform content. Use supported styles, links and interactions for the destination; browser preview does not establish WeChat paste/publishing fidelity. +- For actual email delivery, also read `design-other.md`'s email boundary. An article preview is not email-client verification. + +## Acceptance + +Read the full article in order and inspect its beginning, middle and ending at narrow and wide widths. Check loading/crops, captions, long links, spacing and CTA destinations. Verify requested transfer/export where available; otherwise retain the editable file and identify the unverified destination. Never claim publication without performing the authorized action. diff --git a/.agents/skills/ipollowork-design-studio/references/design-cards.md b/.agents/skills/ipollowork-design-studio/references/design-cards.md new file mode 100644 index 000000000..5fdf52cf0 --- /dev/null +++ b/.agents/skills/ipollowork-design-studio/references/design-cards.md @@ -0,0 +1,23 @@ + + +# Card Series Rules + +Use for `cards`: social carousels and shareable information card series. Read `design.md` and shared guidelines first. + +## Sequence and capacity + +- Content determines card count unless explicitly constrained. Give each card a clear role and maintain opening, progression and conclusion without forcing separate cards for each. +- Preserve requested channel dimensions and consistent series geometry. Do not convert cards into PPT or impose long-page scrolling on export canvases. +- Reuse typography, margins, attribution and numbering. Vary structure for different content relationships, not simply for decoration. +- Retain sufficient context when cards are shared alone. Keep values, units, sources and qualifications together; do not split claims from conditions to fit. +- Recompose or split dense content within user constraints rather than shrinking text. Keep content editable where supported. + +## Assets and behavior + +- Apply shared media rules across the series. Reuse a coherent visual family and check each crop; avoid redundant generation for repeated subjects. +- Do not bake final copy, figures or real logos into generated illustrations when separate editable objects are required. +- If interactive carousel behavior is requested, test next/previous, focus and touch. Static card exports do not need invented navigation or hover effects. + +## Acceptance + +Inspect every card and the series in order at final size and typical mobile reading scale. Check blank/duplicate cards, lost endings, numbering, safe areas and visual consistency. Verify requested export count, dimensions and order; report untested export behavior separately. diff --git a/.agents/skills/ipollowork-design-studio/references/design-other.md b/.agents/skills/ipollowork-design-studio/references/design-other.md new file mode 100644 index 000000000..d8c42727f --- /dev/null +++ b/.agents/skills/ipollowork-design-studio/references/design-other.md @@ -0,0 +1,22 @@ + + +# Other Design Rules + +Use for `other` when no existing category fits the active artifact. Read `design.md` and shared guidelines first. Do not silently change an existing manifest to fit the routing table. + +## Establish the contract + +- Infer purpose, audience, canvas/viewport, editable content and format from the request/current files. Ask only about missing choices that materially change delivery. +- Record constraints briefly in the task. Do not invent a new category, runtime, app scaffold or specification file. +- Borrow relevant checks from the nearest type: site responsiveness, poster geometry, report evidence or article readability. Do not import unrelated navigation, pagination or exports. +- Apply shared layout/media rules. Without a dedicated catalog, reuse local patterns or create scoped structures with the existing theme. + +## Special delivery boundaries + +- Email: distinguish web mockups from actual email HTML. Establish target clients and a supported export/transfer path. Use compatible structure/styles, non-scripted actions and supported asset delivery. Check narrow layouts, image blocking, fallback text and links. Claim compatibility only for clients actually inspected. +- Image-led work: use media Skills for raster generation/editing; use Design for surrounding editable composition when needed. Raster references do not establish recoverable text layers or native vectors. +- Unusual print/interactive formats: inspect actual runtime/export capabilities before promising them. Continue independent work and identify concrete unsupported requirements. + +## Acceptance + +Verify the inferred contract using real content and the supported preview. Check completeness, readability, geometry, assets and relevant interactions; inspect requested exports when available. Identify which type checks were used and remaining limitations. HTML validity alone cannot establish acceptance of an unknown format. diff --git a/.agents/skills/ipollowork-design-studio/references/design-poster.md b/.agents/skills/ipollowork-design-studio/references/design-poster.md new file mode 100644 index 000000000..b57b75618 --- /dev/null +++ b/.agents/skills/ipollowork-design-studio/references/design-poster.md @@ -0,0 +1,22 @@ + + +# Poster and Banner Rules + +Use for `poster`: a single promotional canvas, poster or banner. Read `design.md` and shared guidelines first. + +## Canvas and hierarchy + +- Use requested dimensions, aspect ratio and viewing context. Preserve the existing canvas when unspecified; clarify only consequential missing dimensions. Do not inherit PPT's 16:9 requirement. +- Establish a focal message, supporting information and action. Preserve required dates, locations, terms, logos and contact details without treating sample copy as mandatory. +- Maintain safe margins and deliberate alignment. Fixed export canvases scale for preview without composition reflow. Responsive web banners may need a separate narrow composition; inspect each requested variant. +- Keep text/graphics editable where supported. Do not replace all content with a generated raster poster when editability is required. + +## Assets and output + +- Follow shared media rules for campaign, subject and atmosphere imagery. Preserve real product geometry and brand marks; never fabricate sponsors or endorsements. +- Judge resolution at final export size. Check crops, contrast, important subjects and text over images. Keep QR codes undistorted and test their destination when present. +- Apply print bleed, color-space and production requirements only when requested and supported. Browser HTML alone does not prove press-ready output. + +## Acceptance + +Inspect the entire canvas at final dimensions and intended reading scale. Check required copy, safe margins, overlap, sharpness and brand proportions. Inspect actual exports when requested; distinguish editable HTML from verified raster/print output. Static delivery needs no decorative animation. diff --git a/.agents/skills/ipollowork-design-studio/references/design-report.md b/.agents/skills/ipollowork-design-studio/references/design-report.md new file mode 100644 index 000000000..96be73125 --- /dev/null +++ b/.agents/skills/ipollowork-design-studio/references/design-report.md @@ -0,0 +1,22 @@ + + +# Report Rules + +Use for `report`: research, business and data-led documents. Read `design.md` and shared guidelines first. + +## Evidence and reading structure + +- Organize around the question, findings, evidence, implications and limitations. Include methodology/source notes when needed; do not pad to a sample section count. +- Preserve facts, units, time ranges, denominators and qualifications. Separate measured data, estimates and assumptions. Missing evidence is a gap, not permission to invent data or citations. +- Use editable tables/charts for comparisons, trends and relationships. Label axes, units, legends and sources; avoid misleading visual encodings. +- Keep heading, summary, caption and note hierarchy consistent. Associate charts with explanations. Long reports may need working section links or a contents list. + +## Medium and assets + +- Distinguish responsive screen reports from paginated print/PDF. Preserve the active format; do not impose PPT geometry or promise pagination from HTML alone. +- Handle long tables intentionally: readable labels, headers and access to all columns. Inspect screen scrolling and actual page breaks for requested print output. +- Apply shared asset rules to useful contextual imagery. Generated images cannot replace research evidence, source charts or real case photography. + +## Acceptance + +Check source-to-output completeness, values and citations. Inspect all sections for clipping, repeated headings and unreadable density. Test screen navigation and narrow layouts. Inspect actual requested exports for blank pages, cropped tables and orphaned headings. Report factual uncertainty separately from layout quality and untested formats. diff --git a/.agents/skills/ipollowork-design-studio/references/design-site.md b/.agents/skills/ipollowork-design-studio/references/design-site.md new file mode 100644 index 000000000..c6cdc3321 --- /dev/null +++ b/.agents/skills/ipollowork-design-studio/references/design-site.md @@ -0,0 +1,23 @@ + + +# Website Rules + +Use for `site`: websites, landing pages and portfolios. Read `design.md` and shared guidelines first. + +## Content and layout + +- Organize around audience, main promise, evidence and intended action. Sample feature, pricing and testimonial sections are optional patterns, not quotas. Never invent prices or endorsements. +- Reuse fitting source or supplied library sections; adapt or compose new sections in the current visual language. Do not reduce every relationship to a card grid. +- Use semantic landmarks and coherent headings. Align DOM and visual reading order; navigation labels must lead to real destinations. +- Use fluid layouts, readable measure, flexible media and content-driven breakpoints. Inspect narrow phone, intermediate and desktop widths, including the intended minimum width. Do not shrink a desktop canvas into unreadable mobile content. + +## Assets and interaction + +- Apply shared asset/model rules. Product and context imagery may help without being indispensable. Set intrinsic image dimensions, suitable alternative text and deliberate crops at each width. +- Keep primary content readable while media loads and when motion is reduced or enhancement fails. Animation must not block reading. +- Test menus, anchors, links, forms and primary actions with pointer and keyboard. Handle focus, validation and supported loading/error/success states. Never present local prototype feedback as a real service submission. +- Preserve the supported runtime; a static HTML task does not authorize a backend or app source changes. + +## Acceptance + +Inspect the full page, including below the fold, at representative widths. Check overflow, long localized titles, navigation collisions, crops, focus visibility and touch usability. Exercise real destinations and form behavior. Recheck after theme changes and asset insertion. Report disconnected integrations and untested viewports; a desktop screenshot alone is not responsive acceptance. diff --git a/.agents/skills/ipollowork-design-studio/references/design.md b/.agents/skills/ipollowork-design-studio/references/design.md new file mode 100644 index 000000000..e3deae93e --- /dev/null +++ b/.agents/skills/ipollowork-design-studio/references/design.md @@ -0,0 +1,29 @@ + + +# Design Type Routing + +Read the [shared guidelines](shared-guidelines.md), then only the active type reference below. The session contract, manifest category, editable path and actual export capabilities are authoritative. Do not ask the user to choose an internal category when the task is clear. + +| Manifest category | Scope | Type reference or handoff | +| --- | --- | --- | +| `site` | Websites, landing pages and portfolios | [Website](design-site.md) | +| `app` | Application screens, dashboards and interactive prototypes | [Application](design-app.md) | +| `slides` | HTML presentations and native editable PPTX | Use `ipollowork-presentations`; repository template authors read `slides-ppt.md` and `layout.md` | +| `poster` | Posters, banners and single-canvas promotional designs | [Poster](design-poster.md) | +| `cards` | Social carousels and shareable information card series | [Cards](design-cards.md) | +| `report` | Reports, research summaries and data-led documents | [Report](design-report.md) | +| `article` | Editorial pages, long-form reading and WeChat articles | [Article](design-article.md) | +| `other` | Designs with no fitting existing category | [Other](design-other.md) | +| `video` | Timed compositions on the Video surface | Use `ipollowork-video-studio`; repository template authors read `video.md` | + +Landing, social, email and image are not additional manifest categories. Route landing pages to `site`, social card sequences to `cards`, and single promotional visuals to `poster`. Reading-oriented newsletters belong to `article`; actual email delivery also needs the compatibility checks in `design-other.md`. Generated image assets use media Skills. Preserve existing manifests; do not silently recategorize a user's project. + +For mixed artifacts, use the primary deliverable's rules and consult only relevant secondary sections. An embedded chart does not turn a website into a report; a dashboard screenshot does not make a poster interactive. + +## Shared execution boundary + +- Preserve project paths, semantic `--ipw-*` tokens, editor hooks and fixed brand regions. Initial generation adapts structure to content; targeted edits protect unrelated work. +- Apply shared asset rules to every type. A missing image slot or catalog does not remove a useful visual need. Type references add suitability checks, not competing model-selection or authorization policies. +- Read a layout library only when supplied by the session. Prefer fitting catalog or local patterns; extend when none fits. Do not invent catalog paths for categories without a library or require IDs for new structures. +- Inspect real content after fonts/assets load. Verify the requested output, not merely HTML source. Shared-style changes require checking every affected section/page. +- These references are guidance, not evidence of automatic enforcement or completed acceptance. Report source, rendering, interaction, editing and export checks separately. diff --git a/.agents/skills/ipollowork-design-studio/references/shared-guidelines.md b/.agents/skills/ipollowork-design-studio/references/shared-guidelines.md new file mode 100644 index 000000000..a38dc71dc --- /dev/null +++ b/.agents/skills/ipollowork-design-studio/references/shared-guidelines.md @@ -0,0 +1,191 @@ + + +# iPolloWork Shared Creative and Layout Guidelines + +Status: authoring guidance for template application, content generation and subsequent editing, not the client's UI style specification. These requirements do not imply that every engine receives them automatically or that automated checks enforce every rule. A documentation update does not add a loader, visual detector or runtime gate. + +### 1. Purpose and ownership + +Choose structures that serve real content while retaining the template's identity. Deliver work that people can read, edit and run. Use the shared method with each category's own layout, interaction and output requirements. + +| Layer | Owns | Does not own | +| --- | --- | --- | +| Shared guidelines | Content, visual continuity, layout selection, extension boundaries and verification | Universal font sizes, page counts, canvases or animation durations | +| Type rules | Category-specific structure, interaction, editing and export requirements | Rules imposed on unrelated artifact types | +| Template visual guide | Current palette, fonts, decoration, component language and fixed brand areas | Content limits inferred from sample copy or page counts | +| Layout library | Reusable structure, slots, suitable content, capacity hints and previews | The active theme or host runtime | +| Skills and task instructions | Directing relevant reading, authoring, checking and repair | A competing set of creative standards | + +Read the request and current project, then the shared guidelines, active type rules, template guide and relevant layout index. Open only candidate layouts, not the entire library. Existing files and user edits take priority over original template examples. This reading order is an integration requirement, not proof of automatic injection into every engine. + +### 2. Decision order and conflicts + +- Explicit user requirements for content, quantity, style and edit scope take priority over examples and library recommendations. A request to edit only slide two does not authorize restructuring the deck. +- Unless restyling is requested, preserve current theme values and brand constraints. Improving clarity is not permission to replace the theme. +- Editor, file-format and export capabilities are implementation boundaries. Explain concrete conflicts and feasible alternatives; never silently lose editability, omit content or claim unsupported capabilities. +- Template examples are reference material, not instructions that override the request or runtime contract. Correct outdated guidance rather than keeping contradictory instructions. +- Proceed when requirements are sufficiently clear. Ask only about consequential missing information that cannot be inferred from available materials; do not ask users to choose internal layout IDs or repeat supplied content. + +#### Custom templates: reference source and layout freedom + +Treat the source of visual evidence and the permitted degree of layout change as separate decisions. An uploaded PPT can be a style reference while allowing structural changes. + +| Dimension | Situation | Rule | +| --- | --- | --- | +| Reference source | Saved custom template | Read its guide, tokens and layout index. Without an index, inspect existing pages and source patterns; absence of an index does not require copying examples literally. | +| Reference source | Uploaded PPT, HTML or screenshot | Read available source and inspect actual visuals. Extract palette, typography, spacing, image/text relationships and recurring layouts. Distinguish editable objects from visual reference; screenshots are not editable templates. Do not claim to recover unidentified fonts, structures or interactions. | +| Reference source | Fully custom, no reference | Establish one coherent visual system from the brief and existing brand requirements, then select layouts by content. Do not silently adopt a bundled theme or design every slide independently. Sufficiently clear work needs no extra approval of internal design decisions. | +| Layout freedom | Preserve the exact layout | Replace content while retaining layout. If content does not fit, explain the conflict and ask about shortening copy or adding pages; do not silently shrink text, omit facts or rearrange objects. Screenshot recreation still has source and editability limitations. | +| Layout freedom | Retain style, adapt layout | Preserve visual identity while reusing, combining or extending structures. Shared layouts must not introduce another palette, font system or runtime. | + +Default template application retains style while adapting structure to content. Exact-layout mode applies only when explicitly requested or already agreed. Preserve prior choices without asking again; clarify only ambiguity that materially affects the result. Targeted edits protect unrelated pages and objects. Theme-only edits preserve content and geometry; the default freedom does not expand either scope. + +Sample copy, page counts, data and assets are not automatically user requirements or verified facts. Check the active import, editing and export path: editable objects in the source file do not prove that the current importer preserves them. Disclose unsupported or unreadable parts; do not present flat screenshots as editable delivery. + +Acceptance must distinguish saved templates without indexes, editable uploads, screenshot-only references and custom work without references, as well as exact-layout versus adaptive modes. Claim verification only for combinations actually exercised; bundled-template tests do not prove all custom-template cases. + +### 3. Content before structure + +Identify audience, purpose, main message, supporting material and intended action before organizing pages, sections or scenes. + +- Content determines page count, scene count and duration. Examples are not quotas. Only explicit user quantities constrain the result; distinguish approximate targets from strict limits. +- Separate facts, goals, assumptions and unresolved information. Never invent data, sources, testimonials, customer logos, prices or outcomes to fill a layout. +- Preserve important facts, conditions, units and source relationships. Tighten wording without removing qualifications or evidence merely to fit. +- An empty slot may mean the structure is unsuitable. Remove unnecessary slots or change layout instead of padding with meaningless copy. +- Produce actual files when information is sufficient. If confirmation is necessary, pause only dependent work. A confirmed video script does not need the same approval again. + +### 4. Preserve visual identity + +- Retain the current palette, typography, radii, decoration and overall character by default. A new topic or audience does not authorize a brand redesign. +- Use current semantic `--ipw-*` tokens. Keep structural CSS separate from theme values; do not create another theme in inline styles or scripts. Follow the Design-System Layer contract below where applicable. +- Shared layouts supply structure and capacity guidance. Map them to the active visual language; omit preview palettes, fonts, hosts and demo scripts. +- Preserve proportions of logos, icons and photos. Keep fixed brand areas; update editable brand slots from user content. Demo logos are not customer endorsements. +- Do not categorically reject particular colors, serif fonts, gradients or symmetry. Judge readability, template intent and user requirements rather than imposing a universal aesthetic. +- Theme changes must not rewrite content, replace images or reorder pages. Check actual typography after font changes to catch new overflow. + +### 5. Select and extend layouts + +Identify the content relationship: statement, comparison, process, data, case study, hierarchy or summary. Compare local and shared patterns and prefer a suitable structure that retains the style; neither source has unconditional priority. + +The catalog is a preferred reuse source, not an ID whitelist or a complete inventory of extracted templates. Local source patterns remain valid even when absent from the global catalog. When none fits, write a new layout within the current visual language and record its origin, relationship, slots and capacity in the page plan. A new ID, missing global registration or missing provenance attribute is not grounds for rejection. Validate content fit, rendered layout and type contracts. Do not label a one-off extension as a verified library pattern; admission requires separate real-content, client-preview and applicable export checks. + +| Situation | Action | +| --- | --- | +| Relationship and capacity fit | Reuse, replace content and check actual rendering | +| Relationship fits; capacity differs slightly | Adjust columns, proportions, alignment, image/text area or optional slots | +| Relationship does not fit | Select another pattern; do not force a sequence into unordered cards | +| No suitable existing structure | Extend with the current template's visual elements and retain the type runtime contract | +| Exact layout is required but content will not fit | Explain the conflict and offer copy reduction or additional pages/scenes; do not omit content without permission | + +Extension is not a theme change. Scope new CSS locally so one edit does not affect unrelated pages. Repeat structures when comparison benefits from consistency; do not force variety or turn everything into the same card simply for convenience. + +Capacity is a selection hint, not a hard limit on user content. First tighten nonessential wording, then adjust space, choose a better structure or split within user constraints. Do not default to shrinking all text, compressing line height or clipping important content. + +Fixed-canvas presentations retain the established aspect ratio and coordinate system. Do not use negative positioning, viewport-dependent `@media`/`@container` reflow or off-canvas hiding as overflow workarounds. Adjust structure, remove unused slots or redistribute content. `overflow: hidden` may define the canvas boundary, never conceal titles, body text or editable objects. An intentional local offset must be judged by actual bounds and output, not rejected solely because it is negative. + +### 6. Hierarchy, spacing and Chinese typography + +Each reading region should make the entry point, grouping and next step clear. Establish hierarchy through size, weight, position, whitespace and color without forcing every region into an identical heading scale. + +- Keep roles consistent: peer headings, body copy, captions and data labels need coherent styles. Equal relationships use equal spacing; different relationships may use different spacing. +- Clearly associate headings with body copy, charts with captions, and values with units. Check both crowding and gaps that interrupt the reading relationship. +- Multiline Chinese titles must not inherit tight English leading or negative tracking blindly. Check the actual font, weight and canvas for glyph collisions; handle mixed scripts locally. +- Avoid short last lines consisting of a lone Chinese character and punctuation. Break at meaningful boundaries. `text-wrap: balance` helps but cannot replace screenshot review or guarantee intact phrases. +- Hard breaks that work on desktop may create orphans on narrow websites; check breakpoints. Do not convert a fixed PPT canvas into vertically stacked web content. +- Keep values, units, headers and notes aligned. Do not clip chart labels. Choose text sizes by artifact type, viewing distance and template rules; the client's 14px chat text is not a PPT or video body-text standard. +- Inspect reading rhythm and density visually as well as geometrically. Staying inside bounds does not establish good layout. + +### 7. Color, media and motion + +- Use color consistently for hierarchy, brand or state. Important distinctions must not rely on color alone. Check text, controls and charts against actual backgrounds; type rules define applicable contrast targets. +- Emphasis serves content. Do not impose arbitrary accent-color quotas or add glows, icons, cards and backgrounds foreign to the template language. +- Motion should support sequence, feedback or narrative. Website interaction and video storytelling do not share one fixed-duration rule. Reduced-motion interaction preferences must not silently rewrite an exported video's timeline. +- Video uses its supported deterministic timeline so seeking, playback and export agree. Web animation must not block reading or interaction and should support reduced motion where appropriate. Static deliverables need no decorative animation merely to demonstrate capability. + +#### Asset selection, authorization and generation + +This workflow applies to all Design categories and video. Shared guidance decides when assets are useful, when user input is needed and what delivery requires. The media workbench plugin and corresponding Skills own capability queries, model parameters, submission, job status and result placement; type rules must not implement competing call flows. + +For initial creation and full redesign, decide useful visuals **before choosing layouts**. Scene, story, place, people, product and cover content normally merits image consideration; data/process/architecture normally merits editable diagrams. Suitable existing assets should be reused. Images need not be indispensable, and there is no image quota. A text-only attachment, an imageless catalog example, editable PPT mode or a self-chosen geometric style is not a reason to skip imagery. An illustration may evoke autumn or explain a warehouse scenario; label it as illustrative and never claim it is documentary evidence. + +Use one three-step workflow for template application and custom creation: + +1. **Plan and query.** Discover `media/artifact_media_review` through the host extension tools and call `phase="plan"` before layout. Pass the active workspace-relative HTML `sourcePath` and concise `needs` (`id`, `purpose`, `kind`: `image`, `video`, `reuse` or `diagram`). The host records the plan in the existing `brief.json` and performs live capability queries for image/video needs. Read the returned capabilities; plugin installation or a chat model name is not proof of media authorization. Do not write a separate assessment document. An empty plan requires a specific exemption (`explicit-text-only`, `no-generation`, `local-edit`, `theme-only`, `existing-assets` or `diagrams-sufficient`) and reason grounded in the user's scope and content. Do not use diagrams-sufficient merely because shapes can be drawn. Reuse needs still require delivery placement checks. Keep existing planned needs across retries. +2. **Resolve and produce.** Use the model-selection table below, then the image-generation/media-use Skill for actual generation, saving and insertion. Do not ask for per-page approval or another generation confirmation within authorized scope. Preserve real evidence, relevant existing files, and scope/cost constraints. Call job status/recovery for uncertain submissions before retrying. A submitted request is not a saved asset. Save to the current project's `assets/` and use relative URLs. If capability querying, authorization or generation fails, continue independent file work with a coherent fallback and report the specific limitation; do not open settings or wait for authorization. If the user still needs to choose a model, keep the image pending rather than quietly abandoning it. +3. **Check before delivery.** Call `media/artifact_media_review` with `phase="check"`, the same `sourcePath`, and one outcome per planned id. Use `generated`/`reused` with a project-relative `path`; a generated copy also includes the original workspace-relative `generationPath` returned by the tool. The host verifies nonempty files, HTML/CSS references and actual session generation receipts. Use `diagram` only for a planned diagram. Pending or missing items must be resolved; a second empty plan or geometric replacement does not satisfy a planned image. `declined`, `unavailable` and `failed` require specific reasons and are reported partial media delivery, not successful generation. Preserve the actual tool/user evidence; the validator does not independently prove consent, authorization failure or relevance. Independently preview the final result to check cropping, visibility, meaning and playback. If the host review action itself is unavailable, disclose that verification gap rather than claiming it ran. + +| Model condition | Action | +| --- | --- | +| User explicitly selected an available, suitable model | Use it; preserve the choice within the task | +| Explicit model unavailable or unsuitable | Explain and ask before substituting unless alternatives were authorized; continue independent work | +| No explicit model; verified suitable saved preference or approved automatic-selection policy | Follow it within scope and cost settings | +| Exactly one suitable authorized model and no preference | Use it within scope | +| Multiple suitable models and no preference/policy | Ask once before image-dependent pages; keep the asset pending and continue independent work. Do not silently choose `defaultModel` or replace imagery with shapes | +| No authorized suitable model | Continue the file with reuse or a coherent editable fallback and report the unavailable asset; do not guide to settings | +| Query failed | Report capability as unknown, not unauthorized; continue with a disclosed fallback | + +The API's `defaultModel` is a computed candidate, not a saved preference. Save preferences only on explicit request when supported. Recheck capability when the model, operation, parameters or authorization changes, or an error requires it. Never request keys in chat or invent prices, budgets or authorization state. + +The catalog owns structural relationships and reusable fragments, not media policy. Adapt a fitting layout to a useful asset; write a new composition when needed. Type rules add only medium-specific constraints: fixed canvas/editable objects for PPT, responsive loading for web, source evidence for reports, and timing/synchronization for video. Completion checks must exercise the actual query → selection → generation → saved file → insertion path; valid HTML or installed rules alone do not prove it. + +### 8. Interaction and artifact state, where applicable + +Apply this section only to interactive artifacts or regions. Static PPT pages do not need unrelated forms or queues. + +- Buttons, links and menus need real destinations and appropriate pointer, keyboard and focus behavior. +- Cover normal, loading, empty, failed and successful states as relevant. Offer retry/cancel only when actually supported. +- Local prototype feedback is acceptable when clearly identified as disconnected from real services. Do not fabricate submission, payment or save success. +- Distinguish unfinished generation, partial delivery and editable outputs. Existing files do not mean the entire task is done. Link to real files and identify specific gaps. + +### 9. Author, inspect and repair + +1. **Read:** request, current project, type constraints, template guide and relevant layouts. +2. **Plan:** identify each page/section/scene's asset purpose, available files and gaps; query as required by section 7, then select or create structures. Explain key decisions briefly without requiring approval of internal layout IDs. +3. **Implement:** generate within existing authorization and model choices, save/place real content, preserve theme/runtime contracts and limit extensions to necessary changes. +4. **Programmatic checks:** use existing type/package validators for what they actually cover and record tool names and results. +5. **Real experience:** render at target canvas/viewport sizes; check reading, interaction, editing and requested formats. +6. **Local repair:** locate issues by page, element or timestamp; fix and retest affected areas. Shared CSS changes require checking every affected page. +7. **Deliver:** provide real artifacts and distinguish verified, unverified and unfinished work. + +Record asset verification separately from layout verification: purpose/gaps, actual required capability calls, reasons for generating or not generating, saved files and placement. Distinguish no generation needed, reuse, generated, unavailable authorization/tools, and query/generation failure. `unavailable` or `failed` is an accepted completion status when the file continues with a coherent fallback. Without call evidence, do not claim a query occurred or authorization is absent. A selected layout, valid HTML or verbal assertion cannot substitute for asset evidence. Keep records in the task, not additional user forms. + +Self-checks include representative short content, long Chinese titles and dense content; type rules determine exact cases. Source checks cannot substitute for missing rendering/export access. Preserve files, state limitations and tie repair cycles to observed failures rather than regenerating the whole artifact repeatedly. + +#### Executable verification and repair requirements + +- Before authoring, establish available preview, capture and export entry points. Prefer the client and supplied tools; if none is known, make one targeted environment check. Do not repeatedly scan the system or install browsers/dependencies to hide a verification gap. Continue independent work while marking visual acceptance unverified. +- Verify real content, final fonts and saved assets after fonts/images load. Record page/section/timestamp, observed issue, repair and recheck in the task's existing record; do not create a parallel project-file system. +- DOM bounds and resource checks identify candidates; screenshots establish reading quality. Neither excess `scrollHeight` nor successful package validation alone proves visual failure or success. Inspect title/body overlap, contrast on real backgrounds and obvious orphans in rendered output. +- Fix required issues directly when within authorization and scope. Do not deliver known defects as normal completed work. If repair conflicts with exact layout, fixed page count or theme-only scope, explain the concrete tradeoff and ask only about it. +- Re-render after every repair, using evidence from the latest files. Recheck all pages affected by shared-style changes. After two consecutive unsuccessful attempts at the same issue, choose a simpler suitable structure; if still blocked, preserve work and report it instead of looping or marking failure passed. +- Report content, structure, visual, editing and export results separately. Image generation success proves only the asset path; overlap means visual verification fails, and an unperformed export remains unverified. + +### 10. Acceptance levels and implementation status + +These are review categories, not claims of deployed automated enforcement. Preserve user files when reporting required repairs. + +| Level | Examples | Delivery treatment | +| --- | --- | --- | +| Must fix | Missing/fabricated essential content, obscured text, broken assets, necessary interaction/playback failure, flattened output when editability is required | Do not claim complete acceptance; repair or identify the blocker | +| Should fix | Unrequested theme drift, title orphans, inconsistent peer styles, unclear grouping, visibly uneven spacing | Repair and review; explain justified exceptions | +| Optional refinement | Nonessential decoration, rhythm or motion polish | Stay within style/scope and do not delay essential delivery | + +Actual automated coverage comes from service schemas, product validators and returned checks. Some package paths/fields, structures, variables and media timelines are checked; aesthetics, semantic completeness, Chinese line breaks and UX are not comprehensively automated. State conditions for screenshot, DOM and real-operation evidence. + +### 11. Type boundaries and acceptance + +Use the Design routing index to read only the active category. Existing PPT and Video workflows remain separate; shared principles do not impose one canvas or navigation model. + +| Category | Additional requirements | Acceptance evidence | +| --- | --- | --- | +| `slides` | Narrative, capacity, fixed canvas, editable objects and export | Every slide rendered; requested exports inspected | +| `site` | Responsive sections, semantics, navigation/forms and loading | Representative widths and working primary actions | +| `app` | Task flows, data density, controls and states | Main flow and relevant empty/error/recovery cases | +| `poster` | Target canvas, focal message, safe areas and resolution | Complete canvas at target size and requested export | +| `cards` | Sequence, per-card capacity and series consistency | Every card, correct order and requested export count | +| `report` | Evidence, charts/tables, hierarchy and pagination | Source/value checks, full report and requested print output | +| `article` | Reading rhythm, attribution and publishing compatibility | Full reading flow and actual target transfer when available | +| `other` | Explicit medium and capability contract | Relevant borrowed checks and stated format limitations | +| `video` | Pacing, timeline, narration/captions and synchronization | Key frames, seek/playback and requested exports | + +Rule coverage is not tested generation coverage. Validate representative real artifacts category by category, then feed cross-type findings into the shared source. A successful PPT does not prove another category's rendering, interactions or exports. Define scope, counterexamples and verification before expanding libraries. diff --git a/.agents/skills/ipollowork-presentations/SKILL.md b/.agents/skills/ipollowork-presentations/SKILL.md index 04aa2a81e..ceca52c67 100644 --- a/.agents/skills/ipollowork-presentations/SKILL.md +++ b/.agents/skills/ipollowork-presentations/SKILL.md @@ -7,14 +7,42 @@ description: Create, revise, and verify slide presentations in an active iPolloW Use this Skill for slide and presentation work inside the current iPolloWork Design session. It does not provide or control the built-in presentation canvas, template library, editor, or export UI. +Before initial/full authoring, call `media/artifact_media_review` phase=plan with the active HTML sourcePath and visual needs; follow references/shared-guidelines.md. Before final delivery call phase=check, resolve pending/missing assets and disclose fallbacks. The host queries capabilities and checks saved-file placement and generation receipts; preview remains required. Do not replace this workflow with a verbal assessment or a self-selected geometric style. + +## Required references + +Before authoring, read [Shared creative guidelines](references/shared-guidelines.md), then [PPT authoring and verification rules](references/slides-ppt.md) and the [PPT layout guide](references/layout.md). Resolve both relative to this installed Skill, not the user's project or a repository checkout. These packaged references carry the detailed rules; the workflow below is an execution summary. If a reference is missing, report an incomplete Skill installation rather than claiming to have followed it. + ## Workflow 1. Use the exact presentation entry file supplied by the active session and read it before editing. -2. Read the confirmed brief and template metadata when present. -3. On the initial brief application, plan a content-led narrative and page count, then select, repeat, recombine, remove, or reorder the installed template's slide patterns. Do not inherit its sample slide count, order, copy, or assets unless they fit the brief. +2. Read the confirmed brief and template metadata when present. Identify whether this is initial creation, a narrative rewrite, a targeted edit, or a theme-only change. For theme-only changes, preserve content, slide count/order, assets and object geometry; check font fit without silently rearranging the deck. +3. For initial creation and full redesign, assess each page's message, content relationship, asset purpose, reusable files and missing imagery before committing to a layout. Query capabilities where required by the shared guidelines, then choose a fitting public/local layout or write a new one. For product, people, place, case-study or cover imagery with no suitable existing asset, actually query the media service before settling on a text/geometric-only design. Lack of source photos does not mean illustration generation is unavailable. Explicit pure-text requests, content fully served by editable charts, theme-only edits and explicit no-generation requests do not require this query; choosing a geometric design yourself is not a pure-text user request. Let content and explicit user constraints determine narrative and page count; select, repeat, recombine, remove or reorder template patterns. Do not inherit sample counts, order, copy or assets. Do not require an extra outline approval unless the user requests it or a consequential choice remains unresolved. 4. Preserve the template's distinctive visual system, fixed stage, navigation/runtime behavior, editable object contract, and `design-tokens.css` link so Design System controls and exports continue to work. 5. For targeted and follow-up edits, preserve unrelated user-authored slides and content. Never replace the deck with a generic presentation. 6. Keep source files, supporting assets, and requested exports inside the current `design//` directory. -7. Check narrative order, visible content, canvas bounds, editability, and requested export output before reporting completion. +7. Before composing, establish an available preview/capture path and each chosen layout’s content capacity. Follow the references’ render → inspect → local repair → re-render loop on every slide with final fonts and saved assets. Fix overlap and unreadable contrast within scope, then Chinese orphan endings and spacing; do not stop at source validation or successful image generation. Check editability and requested exports separately. Missing render access means visual verification is incomplete, not passed; avoid repeated environment scans or ad hoc dependency installation. The active session's injected Design and template contracts remain authoritative whenever they are more specific. + +## Custom template scope + +Apply the shared guidelines’ separate source and layout-freedom decisions. A saved custom template without a catalog can supply reusable patterns from its source; an uploaded PPT/HTML or screenshot supplies only the evidence actually available. A screenshot is not an editable template. With no reference, establish a coherent visual system from the brief and existing brand requirements. Default to retaining style while adapting structure to content; preserve exact layout only when explicitly requested or already agreed. Targeted edits and theme-only changes keep their narrower scope. Public layouts never override the custom visual identity. Verify actual import/edit/export support rather than promising source fidelity from the file type alone. + +## Content-led layout adaptation + +Follow the injected template layout contract. Extract the template's type hierarchy, palette, spacing rhythm and graphic primitives before composing. Choose layouts by slide purpose: comparison, timeline/process, evidence/chart, case study or key statement. Reuse a fitting slide, vary its proportions and emphasis, or build a new composition from those primitives. Keep the fixed stage and editable-object contract; extending layouts does not permit unsupported export elements. + +Respect explicit exact-layout requests and leave unrelated slides unchanged during targeted edits. Review the deck as thumbnails and at presentation size for narrative rhythm, repeated layouts without a content reason, dense text, clipping and visual consistency. Split or recompose when allowed by the user's page constraint; do not shrink text or omit facts just to fill an inherited layout. + +For slides and sites, read `core-v1-index.md` beside `brief.json` first, then only the active type's `core-v1-slides/` or `core-v1-site/` catalog, layout guide and shared contract. The index maps shared content relationships; implementations remain type-specific. PPT keeps its fixed canvas and supported editable markers; websites use responsive flow and semantic interactions. Video uses the Video Studio workflow and its `core-v1-video/` catalog with separate timing and playback constraints. Reuse fitting global or local patterns; new layouts remain valid. Copy only structural fragments and scoped styles, excluding preview hosts, palettes and scripts. Preserve the active template's tokens unless restyling is requested, and verify real content/assets under the type rules. Catalog verification never substitutes for current delivery checks. + +## Media and mode boundaries + +Use the shared guidelines' visual-purpose and model-selection rules as the single decision policy. During page planning, identify the visual benefit, reusable assets and best medium internally; do not create a separate assessment report or approval step. Proactively supplement useful product, people, setting, story and cover imagery. Prefer editable charts/process/architecture diagrams; pure decoration does not require generation. Use image-generation for supporting images even when Studio is closed. Native editable PPT supports image objects, and a text-only attachment or geometric example does not prohibit imagery. Resolve the model once for compatible assets. When multiple suitable models have no task preference or approved automatic policy, ask once before image-dependent pages; never silently use defaultModel or downgrade to shapes. Continue independent text/layout work with the asset pending, and do not claim complete delivery until the choice is answered or the user declines. Never substitute an explicitly limited model without permission. Missing authorization or query/generation failure must not block the file: report the actual asset state and use a coherent fallback without opening settings. Generate during authoring and verify saved-file placement before delivery; generated scenes cannot replace real evidence. + +For native editable PPT, retain supported object markers and let the Design panel own navigation. Do not add presentation scripts, keyboard handlers, controls, speaker-note nodes, responsive reflow or unsupported animation. If notes are requested but cannot be embedded, provide a separate script with the limitation stated. For HTML presentations, retain only the current template's supported runtime, notes and motion; keep presenter-only instructions out of visible slide content. HTML playback is not proof of native PPTX support. Keep text and shape markers on separate elements; verify exported text coverage. If no callable product export capability is available, report that limitation and direct the user to the client export UI. Do not reconstruct an approximate PPTX with an unrelated script and call it the native export. + +## Completion evidence + +Check source fidelity and structure, the whole-deck overview, and every slide at presentation size. Verify the asset decision separately from layout validity: retain the reason for reuse/generation/no generation, actual required capability calls, saved files and placement, or an accurate pending/unavailable/failed status in the task record. No capability call means capability and authorization were not checked; it does not mean no model is authorized. Do not require a fixed image count. Review long Chinese titles, dense pages, charts and new layouts. Exercise the relevant editor capabilities and actually produce and inspect requested exports, including PPTX editability when required. Fix affected pages and recheck shared-style impacts. Report actual artifact paths and distinguish source checks, rendered checks, editor checks, export checks and remaining gaps; never claim an unperformed check passed. diff --git a/.agents/skills/ipollowork-presentations/references/layout.md b/.agents/skills/ipollowork-presentations/references/layout.md new file mode 100644 index 000000000..85095b257 --- /dev/null +++ b/.agents/skills/ipollowork-presentations/references/layout.md @@ -0,0 +1,141 @@ + + +# PPT Layout Guide · core-v1 + +This guide describes the ten reusable structures currently in the iPolloWork PPT library. It explains when to choose each structure, how to map content into it and when to adapt or replace it. The library is a preferred reuse source, not a mandatory whitelist or a complete inventory of template-local layouts. Use a better-fitting local pattern or write a new one when necessary, retaining the active visual and editable contracts. + +Start with `../core-v1-index.md` beside the session's category directory for shared relationships and type routing. This guide supplies PPT-specific fit and adaptation; shared creative/media policy remains in the shared guidelines. + +## Locate the source + +For a session that declares `layoutLibrary: "core-v1"`, the server materializes `core-v1-slides/` beside `brief.json`. This directory contains the quick index `catalog.md`, this `layout.md`, `shared-contract.md`, `shared.css` and the ten HTML files below. Resolve those files from the current session, not from the installed Skill's `references/` directory. A Skill-packaged copy of this guide is documentation, not a second copy of the HTML library. + +If the directory is absent in an older session, inspect available local patterns and the active contract. Do not invent file paths, assume missing layouts exist or overwrite the user's project merely to obtain a library. Read only the relevant candidate HTML and styles. + +Repository ownership: this document is maintained in `.codex/skills/ipollowork-template-generation/references/layout.md`. The server bundle and both presentation Skill distributions carry checked copies. Source HTML/CSS lives under `apps/server/bundled-templates/core-v1-slides-*`; the server assembles those flat resources into the session directory above. + +## Selection map + +| Layout file | Content relationship | Main slots | Trial capacity | +| --- | --- | --- | --- | +| `comparison.html` | Two alternatives on shared criteria | Title, option names, criteria, paired evidence, takeaway | 2–3 criteria | +| `statement-visual.html` | One main statement supported by a visual | Eyebrow, title, paragraph, visual | One message and one visual | +| `parallel-principles.html` | Peer principles or capabilities | Title, numbered labels, headings, paragraphs | 2–3 peer items | +| `lead-support.html` | A lead case with supporting observations | Title, case label/heading/body, supporting headings/bodies | One case and 1–2 observations | +| `step-sequence.html` | Ordered actions or learning stages | Title, numbers, step headings/bodies | 3–5 steps | +| `milestone-staircase.html` | Successive milestones earned through evidence | Title, stage/date labels, outcomes, evidence, note | 3–4 stages | +| `editorial-visual.html` | Image-led narrative or setting | Eyebrow, title, paragraph, main visual, caption/source | One image and short explanation | +| `quote-wall.html` | Related but distinct attributed voices | Title, segment, main quote/attribution, supporting quotes/attributions | One lead and 1–2 short quotes | +| `evidence-matrix.html` | Findings across comparable groups or options | Title, column/row labels, findings, details, source | Up to 3 rows × 3 comparison columns | +| `metric-scorecard.html` | One key result with supporting measures | Title, primary label/value/context, supporting labels/values, source | One primary and 2–4 secondary metrics | + +These counts describe trial structures, not quotas or validated limits for every language/theme. Source grids demonstrate particular counts; removing an item also requires adjusting columns, rows and proportions. Content and explicit user constraints determine page count. + +## Reuse procedure + +1. Identify the message, evidence and content relationship. Assess asset purpose, existing files and gaps, and make required capability queries under the shared guidelines before committing to text or geometry. +2. Compare the template's local patterns and relevant entries below. Open candidate source HTML, read `data-layout-description` and `data-slot`, and inspect the actual DOM and `shared.css` dependencies. +3. Read `shared-contract.md`. Copy the selected `
` and the relevant scoped CSS, including shared baseline selectors covering that layout. Omit `html`, `body`, `main`, preview `:root` values and demo scripts. Bind to the active theme's semantic `--ipw-*` tokens. +4. Replace every example and assign valid unique slide/object identifiers and ordering. Retain `data-ipw-slide` and the matching editable-object markers. Optional slots may be removed; update layout geometry accordingly. +5. Generate/reuse and place required assets, then trial real short/dense content and long titles with final fonts. Adjust locally or split within user constraints. Never use all-page font shrinking, hidden overflow or responsive reflow as a fixed-canvas workaround. +6. Check actual rendering, relevant client editing and requested exports separately. Do not claim one-off extensions or untested exports are verified library capabilities. + +The structural library and asset Skills have separate responsibilities. Example shapes do not prohibit imagery. Native editable PPT supports marked image objects; a Markdown source or editability requirement does not justify skipping a required media query. Follow shared model-selection and authorization rules rather than adding another approval flow here. + +## 1. Comparison + +- **Source:** `comparison.html`, `.ipw-layout-comparison`; adapted from Brand Narrative's `.tension` relationship. +- **Use for:** two alternatives evaluated on the same dimensions, with a conditional recommendation. +- **Slots:** `title`, `option-a`, `option-b`, `criterion-1…3`, paired `a-1…3`/`b-1…3`, `takeaway`. +- **Capacity:** trial 2–3 short criteria, concise paired evidence and one takeaway. Keep units and uncertainty comparable across both sides. +- **Variants:** remove an unused row, widen the criterion column, adjust the evidence-column ratio or split dense dimensions across pages. Keep corresponding rows aligned. +- **Avoid:** unrelated items presented as a comparison, invented metrics or long narratives crammed into cells. More than two alternatives may need a table or a new structure. + +## 2. Statement and visual + +- **Source:** `statement-visual.html`, `.ipw-layout-statement-visual`; adapted from Brand Narrative's `.manifesto`. +- **Use for:** an opening, chapter or conclusion centered on one statement. +- **Slots:** `eyebrow`, `title`, `body`, `visual`. +- **Capacity:** start with a 2–3-line title and a 3–5-line supporting paragraph, then measure with the target font and width. +- **Variants:** adjust the column ratio, widen or vertically reorganize the title region, and replace the sample circle with a meaningful image, editable chart or graphic. Keep one dominant focus. +- **Assets:** the circle only demonstrates space. If replacing it with an image, remove `data-pptx-shape`, add `data-pptx-image`, provide actual `src`/`alt`, and revise shape-specific sizing/crop rules. +- **Avoid:** preserving the circle merely because it is in the sample, or letting a long title cover the supporting text. + +## 3. Parallel principles + +- **Source:** `parallel-principles.html`, `.ipw-layout-parallel-principles`; adapted from Brand Narrative's `.voice-spectrum`. +- **Use for:** genuinely peer principles, capabilities or summary points. +- **Slots:** `title`, `label-1…3`, `heading-1…3`, `body-1…3`. +- **Capacity:** 2–3 items, each with a short heading and brief explanation. The source uses three columns; a two-item variant must use two columns rather than leave an empty third. +- **Variants:** reduce columns, balance width against actual copy, remove unnecessary labels or split longer explanations. +- **Avoid:** flattening a hierarchy or sequence into peer cards, or reducing all typography to preserve three columns. + +## 4. Lead and support + +- **Source:** `lead-support.html`, `.ipw-layout-lead-support`; adapted from Brand Narrative's `.expression`. +- **Use for:** one main case/outcome explained by evidence and conditions. +- **Slots:** `title`, `case-label`, `case-heading`, `case-body`, `support-heading-1…2`, `support-body-1…2`. +- **Capacity:** one focused case and 1–2 supporting observations. Keep background, action and result concise and sourced. +- **Variants:** change primary/secondary proportions, remove an unused support block or move excess evidence to another page. The lead region may be adapted to actual imagery plus a readable caption. +- **Avoid:** presenting a single case as universal proof or leaving unused blocks filled with generic text. + +## 5. Step sequence + +- **Source:** `step-sequence.html`, `.ipw-layout-step-sequence`; adapted from `ipollowork.pptx-learning-journey/entry.html`, slide 5, `.chapters`. +- **Use for:** ordered actions, a learning path or a repeatable process. +- **Slots:** `title`, `number-1…5`, `heading-1…5`, `body-1…5`. +- **Capacity:** 3–5 steps, each with a short heading and one explanatory sentence. The five-column example requires especially concise copy. +- **Variants:** reduce the grid to the actual step count, group related steps into phases or move detailed instructions to subsequent pages. Preserve an unambiguous reading order. +- **Avoid:** unordered peer principles, branching workflows disguised as a single line, or long procedural text in narrow columns. + +## 6. Milestone staircase + +- **Source:** `milestone-staircase.html`, `.ipw-layout-milestone-staircase`; adapted from `ipollowork.pptx-venture-blueprint/entry.html`, slide 6, `.staircase`. +- **Use for:** stages where an achieved outcome enables the next stage. +- **Slots:** `title`, `date-1…4`, `heading-1…4`, `evidence-1…4`, `note`. +- **Capacity:** 3–4 stages with a date/phase label, short outcome and evidence line. The first step has the least vertical capacity; check it first. +- **Variants:** adjust actual column count and step heights, shorten nonessential wording or split the roadmap. Heights indicate sequence only, never quantitative magnitude; use a chart for measured values. +- **Avoid:** invented deadlines or progress metrics, lengthy evidence inside the shortest step, and treating decorative height as data. + +## 7. Editorial visual + +- **Source:** `editorial-visual.html`, `.ipw-layout-editorial-visual`; adapted from `ipollowork.pptx-film-treatment/entry.html`, slide 1, `.cover` and `.hero-art`. +- **Use for:** image-led narrative, a setting, an observed subject or a cover where visual context matters. +- **Slots:** `eyebrow`, `title`, `body`, `visual`, `caption`; `visual-placeholder` exists only inside the replaceable demo slot. +- **Capacity:** one main visual, a short title/paragraph and a caption/source. Trial a two-line title; rebalance text width or height for longer titles rather than forcing that count. +- **Variants:** adjust image/text proportions, crop to retain the subject, use contain-fit when cropping would discard evidence, or split the explanation from the image. +- **Assets:** replace the entire placeholder with `Meaningful description`, using a real saved file. Remove the placeholder text and shape marker; supply an accurate caption/source. Editable diagrams may use a purpose-built structure instead. +- **Avoid:** shipping the placeholder, using decorative geometry to bypass required asset discovery, or presenting generated illustration as documentary evidence. + +## 8. Quote wall + +- **Source:** `quote-wall.html`, `.ipw-layout-quote-wall`; adapted from `ipollowork.pptx-research-signals/entry.html`, slide 4, `.quote-wall`. +- **Use for:** related but distinct voices that support or qualify a main observation. +- **Slots:** `title`, `segment`, `quote`, `attribution`, `quote-1…2`, `attribution-1…2`. +- **Capacity:** one main quote of roughly 2–4 rendered lines and 1–2 brief supporting quotes, each with an attribution. Sample quote text is illustrative and must be replaced or removed. +- **Variants:** remove an unused side quote and update grid rows, widen the main quote area, or dedicate a page to a long essential quotation. +- **Avoid:** invented testimonials, unattributed quotes, editing a quotation in ways that change its meaning, or presenting one participant as an entire group's view. + +## 9. Evidence matrix + +- **Source:** `evidence-matrix.html`, `.ipw-layout-evidence-matrix`; adapted from `ipollowork.pptx-research-signals/entry.html`, slide 5, `.matrix`. +- **Use for:** comparable findings across groups, options or contexts with explicit uncertainty. +- **Slots:** `title`, `column-0…3` (including the row-label header), `row-1…3`, `finding-r-c`, `detail-r-c`, `source`. +- **Capacity:** up to three observation rows and three comparison columns plus the row-label column. Each cell holds a short finding and qualifier, not a paragraph. +- **Variants:** reduce actual rows/columns and update the grid, widen row labels, or split by evidence dimension. Keep source, sample definition and limitations visible. +- **Avoid:** invented confidence scores, incomparable data definitions, unsupported rankings, or compressing a large research table into unreadable cells. + +## 10. Metric scorecard + +- **Source:** `metric-scorecard.html`, `.ipw-layout-metric-scorecard`; adapted from `ipollowork.pptx-annual-review/entry.html`, slide 2, `.scorecard`. +- **Use for:** a primary outcome interpreted through a small set of supporting measures. +- **Slots:** `title`, `metric-label`, `metric-value`, `metric-context`, `label-1…4`, `value-1…4`, `source`. +- **Capacity:** one primary metric and 2–4 supporting metrics. The source uses a 2×2 secondary grid; adjust rows/columns when using fewer values. +- **Variants:** reallocate the primary/secondary ratio, use consistent number formatting or split distinct metric families. Include actual units, period, definitions and sources; sample numbers are not user data. +- **Avoid:** incompatible time ranges, unsupported growth claims, value labels separated from units, or oversized numbers that collide after a font change. + +## Verification scope + +The current ten source previews have browser-rendering coverage at 1280×720. The six added patterns also have a longer Chinese title/theme-change check, with image-node replacement exercised for `editorial-visual`. These checks do not establish all-language capacity, real-model selection behavior, complete client editing or native PPTX export fidelity. Verify those separately for the actual task. + +Review all selected pages with real content and final assets, and distinguish source, visual, client and export checks in the task record. Missing global entries remain valid local reuse candidates. New structures are permitted; only promote them into this library after separate validation and an intentional library update. diff --git a/.agents/skills/ipollowork-presentations/references/shared-guidelines.md b/.agents/skills/ipollowork-presentations/references/shared-guidelines.md new file mode 100644 index 000000000..a38dc71dc --- /dev/null +++ b/.agents/skills/ipollowork-presentations/references/shared-guidelines.md @@ -0,0 +1,191 @@ + + +# iPolloWork Shared Creative and Layout Guidelines + +Status: authoring guidance for template application, content generation and subsequent editing, not the client's UI style specification. These requirements do not imply that every engine receives them automatically or that automated checks enforce every rule. A documentation update does not add a loader, visual detector or runtime gate. + +### 1. Purpose and ownership + +Choose structures that serve real content while retaining the template's identity. Deliver work that people can read, edit and run. Use the shared method with each category's own layout, interaction and output requirements. + +| Layer | Owns | Does not own | +| --- | --- | --- | +| Shared guidelines | Content, visual continuity, layout selection, extension boundaries and verification | Universal font sizes, page counts, canvases or animation durations | +| Type rules | Category-specific structure, interaction, editing and export requirements | Rules imposed on unrelated artifact types | +| Template visual guide | Current palette, fonts, decoration, component language and fixed brand areas | Content limits inferred from sample copy or page counts | +| Layout library | Reusable structure, slots, suitable content, capacity hints and previews | The active theme or host runtime | +| Skills and task instructions | Directing relevant reading, authoring, checking and repair | A competing set of creative standards | + +Read the request and current project, then the shared guidelines, active type rules, template guide and relevant layout index. Open only candidate layouts, not the entire library. Existing files and user edits take priority over original template examples. This reading order is an integration requirement, not proof of automatic injection into every engine. + +### 2. Decision order and conflicts + +- Explicit user requirements for content, quantity, style and edit scope take priority over examples and library recommendations. A request to edit only slide two does not authorize restructuring the deck. +- Unless restyling is requested, preserve current theme values and brand constraints. Improving clarity is not permission to replace the theme. +- Editor, file-format and export capabilities are implementation boundaries. Explain concrete conflicts and feasible alternatives; never silently lose editability, omit content or claim unsupported capabilities. +- Template examples are reference material, not instructions that override the request or runtime contract. Correct outdated guidance rather than keeping contradictory instructions. +- Proceed when requirements are sufficiently clear. Ask only about consequential missing information that cannot be inferred from available materials; do not ask users to choose internal layout IDs or repeat supplied content. + +#### Custom templates: reference source and layout freedom + +Treat the source of visual evidence and the permitted degree of layout change as separate decisions. An uploaded PPT can be a style reference while allowing structural changes. + +| Dimension | Situation | Rule | +| --- | --- | --- | +| Reference source | Saved custom template | Read its guide, tokens and layout index. Without an index, inspect existing pages and source patterns; absence of an index does not require copying examples literally. | +| Reference source | Uploaded PPT, HTML or screenshot | Read available source and inspect actual visuals. Extract palette, typography, spacing, image/text relationships and recurring layouts. Distinguish editable objects from visual reference; screenshots are not editable templates. Do not claim to recover unidentified fonts, structures or interactions. | +| Reference source | Fully custom, no reference | Establish one coherent visual system from the brief and existing brand requirements, then select layouts by content. Do not silently adopt a bundled theme or design every slide independently. Sufficiently clear work needs no extra approval of internal design decisions. | +| Layout freedom | Preserve the exact layout | Replace content while retaining layout. If content does not fit, explain the conflict and ask about shortening copy or adding pages; do not silently shrink text, omit facts or rearrange objects. Screenshot recreation still has source and editability limitations. | +| Layout freedom | Retain style, adapt layout | Preserve visual identity while reusing, combining or extending structures. Shared layouts must not introduce another palette, font system or runtime. | + +Default template application retains style while adapting structure to content. Exact-layout mode applies only when explicitly requested or already agreed. Preserve prior choices without asking again; clarify only ambiguity that materially affects the result. Targeted edits protect unrelated pages and objects. Theme-only edits preserve content and geometry; the default freedom does not expand either scope. + +Sample copy, page counts, data and assets are not automatically user requirements or verified facts. Check the active import, editing and export path: editable objects in the source file do not prove that the current importer preserves them. Disclose unsupported or unreadable parts; do not present flat screenshots as editable delivery. + +Acceptance must distinguish saved templates without indexes, editable uploads, screenshot-only references and custom work without references, as well as exact-layout versus adaptive modes. Claim verification only for combinations actually exercised; bundled-template tests do not prove all custom-template cases. + +### 3. Content before structure + +Identify audience, purpose, main message, supporting material and intended action before organizing pages, sections or scenes. + +- Content determines page count, scene count and duration. Examples are not quotas. Only explicit user quantities constrain the result; distinguish approximate targets from strict limits. +- Separate facts, goals, assumptions and unresolved information. Never invent data, sources, testimonials, customer logos, prices or outcomes to fill a layout. +- Preserve important facts, conditions, units and source relationships. Tighten wording without removing qualifications or evidence merely to fit. +- An empty slot may mean the structure is unsuitable. Remove unnecessary slots or change layout instead of padding with meaningless copy. +- Produce actual files when information is sufficient. If confirmation is necessary, pause only dependent work. A confirmed video script does not need the same approval again. + +### 4. Preserve visual identity + +- Retain the current palette, typography, radii, decoration and overall character by default. A new topic or audience does not authorize a brand redesign. +- Use current semantic `--ipw-*` tokens. Keep structural CSS separate from theme values; do not create another theme in inline styles or scripts. Follow the Design-System Layer contract below where applicable. +- Shared layouts supply structure and capacity guidance. Map them to the active visual language; omit preview palettes, fonts, hosts and demo scripts. +- Preserve proportions of logos, icons and photos. Keep fixed brand areas; update editable brand slots from user content. Demo logos are not customer endorsements. +- Do not categorically reject particular colors, serif fonts, gradients or symmetry. Judge readability, template intent and user requirements rather than imposing a universal aesthetic. +- Theme changes must not rewrite content, replace images or reorder pages. Check actual typography after font changes to catch new overflow. + +### 5. Select and extend layouts + +Identify the content relationship: statement, comparison, process, data, case study, hierarchy or summary. Compare local and shared patterns and prefer a suitable structure that retains the style; neither source has unconditional priority. + +The catalog is a preferred reuse source, not an ID whitelist or a complete inventory of extracted templates. Local source patterns remain valid even when absent from the global catalog. When none fits, write a new layout within the current visual language and record its origin, relationship, slots and capacity in the page plan. A new ID, missing global registration or missing provenance attribute is not grounds for rejection. Validate content fit, rendered layout and type contracts. Do not label a one-off extension as a verified library pattern; admission requires separate real-content, client-preview and applicable export checks. + +| Situation | Action | +| --- | --- | +| Relationship and capacity fit | Reuse, replace content and check actual rendering | +| Relationship fits; capacity differs slightly | Adjust columns, proportions, alignment, image/text area or optional slots | +| Relationship does not fit | Select another pattern; do not force a sequence into unordered cards | +| No suitable existing structure | Extend with the current template's visual elements and retain the type runtime contract | +| Exact layout is required but content will not fit | Explain the conflict and offer copy reduction or additional pages/scenes; do not omit content without permission | + +Extension is not a theme change. Scope new CSS locally so one edit does not affect unrelated pages. Repeat structures when comparison benefits from consistency; do not force variety or turn everything into the same card simply for convenience. + +Capacity is a selection hint, not a hard limit on user content. First tighten nonessential wording, then adjust space, choose a better structure or split within user constraints. Do not default to shrinking all text, compressing line height or clipping important content. + +Fixed-canvas presentations retain the established aspect ratio and coordinate system. Do not use negative positioning, viewport-dependent `@media`/`@container` reflow or off-canvas hiding as overflow workarounds. Adjust structure, remove unused slots or redistribute content. `overflow: hidden` may define the canvas boundary, never conceal titles, body text or editable objects. An intentional local offset must be judged by actual bounds and output, not rejected solely because it is negative. + +### 6. Hierarchy, spacing and Chinese typography + +Each reading region should make the entry point, grouping and next step clear. Establish hierarchy through size, weight, position, whitespace and color without forcing every region into an identical heading scale. + +- Keep roles consistent: peer headings, body copy, captions and data labels need coherent styles. Equal relationships use equal spacing; different relationships may use different spacing. +- Clearly associate headings with body copy, charts with captions, and values with units. Check both crowding and gaps that interrupt the reading relationship. +- Multiline Chinese titles must not inherit tight English leading or negative tracking blindly. Check the actual font, weight and canvas for glyph collisions; handle mixed scripts locally. +- Avoid short last lines consisting of a lone Chinese character and punctuation. Break at meaningful boundaries. `text-wrap: balance` helps but cannot replace screenshot review or guarantee intact phrases. +- Hard breaks that work on desktop may create orphans on narrow websites; check breakpoints. Do not convert a fixed PPT canvas into vertically stacked web content. +- Keep values, units, headers and notes aligned. Do not clip chart labels. Choose text sizes by artifact type, viewing distance and template rules; the client's 14px chat text is not a PPT or video body-text standard. +- Inspect reading rhythm and density visually as well as geometrically. Staying inside bounds does not establish good layout. + +### 7. Color, media and motion + +- Use color consistently for hierarchy, brand or state. Important distinctions must not rely on color alone. Check text, controls and charts against actual backgrounds; type rules define applicable contrast targets. +- Emphasis serves content. Do not impose arbitrary accent-color quotas or add glows, icons, cards and backgrounds foreign to the template language. +- Motion should support sequence, feedback or narrative. Website interaction and video storytelling do not share one fixed-duration rule. Reduced-motion interaction preferences must not silently rewrite an exported video's timeline. +- Video uses its supported deterministic timeline so seeking, playback and export agree. Web animation must not block reading or interaction and should support reduced motion where appropriate. Static deliverables need no decorative animation merely to demonstrate capability. + +#### Asset selection, authorization and generation + +This workflow applies to all Design categories and video. Shared guidance decides when assets are useful, when user input is needed and what delivery requires. The media workbench plugin and corresponding Skills own capability queries, model parameters, submission, job status and result placement; type rules must not implement competing call flows. + +For initial creation and full redesign, decide useful visuals **before choosing layouts**. Scene, story, place, people, product and cover content normally merits image consideration; data/process/architecture normally merits editable diagrams. Suitable existing assets should be reused. Images need not be indispensable, and there is no image quota. A text-only attachment, an imageless catalog example, editable PPT mode or a self-chosen geometric style is not a reason to skip imagery. An illustration may evoke autumn or explain a warehouse scenario; label it as illustrative and never claim it is documentary evidence. + +Use one three-step workflow for template application and custom creation: + +1. **Plan and query.** Discover `media/artifact_media_review` through the host extension tools and call `phase="plan"` before layout. Pass the active workspace-relative HTML `sourcePath` and concise `needs` (`id`, `purpose`, `kind`: `image`, `video`, `reuse` or `diagram`). The host records the plan in the existing `brief.json` and performs live capability queries for image/video needs. Read the returned capabilities; plugin installation or a chat model name is not proof of media authorization. Do not write a separate assessment document. An empty plan requires a specific exemption (`explicit-text-only`, `no-generation`, `local-edit`, `theme-only`, `existing-assets` or `diagrams-sufficient`) and reason grounded in the user's scope and content. Do not use diagrams-sufficient merely because shapes can be drawn. Reuse needs still require delivery placement checks. Keep existing planned needs across retries. +2. **Resolve and produce.** Use the model-selection table below, then the image-generation/media-use Skill for actual generation, saving and insertion. Do not ask for per-page approval or another generation confirmation within authorized scope. Preserve real evidence, relevant existing files, and scope/cost constraints. Call job status/recovery for uncertain submissions before retrying. A submitted request is not a saved asset. Save to the current project's `assets/` and use relative URLs. If capability querying, authorization or generation fails, continue independent file work with a coherent fallback and report the specific limitation; do not open settings or wait for authorization. If the user still needs to choose a model, keep the image pending rather than quietly abandoning it. +3. **Check before delivery.** Call `media/artifact_media_review` with `phase="check"`, the same `sourcePath`, and one outcome per planned id. Use `generated`/`reused` with a project-relative `path`; a generated copy also includes the original workspace-relative `generationPath` returned by the tool. The host verifies nonempty files, HTML/CSS references and actual session generation receipts. Use `diagram` only for a planned diagram. Pending or missing items must be resolved; a second empty plan or geometric replacement does not satisfy a planned image. `declined`, `unavailable` and `failed` require specific reasons and are reported partial media delivery, not successful generation. Preserve the actual tool/user evidence; the validator does not independently prove consent, authorization failure or relevance. Independently preview the final result to check cropping, visibility, meaning and playback. If the host review action itself is unavailable, disclose that verification gap rather than claiming it ran. + +| Model condition | Action | +| --- | --- | +| User explicitly selected an available, suitable model | Use it; preserve the choice within the task | +| Explicit model unavailable or unsuitable | Explain and ask before substituting unless alternatives were authorized; continue independent work | +| No explicit model; verified suitable saved preference or approved automatic-selection policy | Follow it within scope and cost settings | +| Exactly one suitable authorized model and no preference | Use it within scope | +| Multiple suitable models and no preference/policy | Ask once before image-dependent pages; keep the asset pending and continue independent work. Do not silently choose `defaultModel` or replace imagery with shapes | +| No authorized suitable model | Continue the file with reuse or a coherent editable fallback and report the unavailable asset; do not guide to settings | +| Query failed | Report capability as unknown, not unauthorized; continue with a disclosed fallback | + +The API's `defaultModel` is a computed candidate, not a saved preference. Save preferences only on explicit request when supported. Recheck capability when the model, operation, parameters or authorization changes, or an error requires it. Never request keys in chat or invent prices, budgets or authorization state. + +The catalog owns structural relationships and reusable fragments, not media policy. Adapt a fitting layout to a useful asset; write a new composition when needed. Type rules add only medium-specific constraints: fixed canvas/editable objects for PPT, responsive loading for web, source evidence for reports, and timing/synchronization for video. Completion checks must exercise the actual query → selection → generation → saved file → insertion path; valid HTML or installed rules alone do not prove it. + +### 8. Interaction and artifact state, where applicable + +Apply this section only to interactive artifacts or regions. Static PPT pages do not need unrelated forms or queues. + +- Buttons, links and menus need real destinations and appropriate pointer, keyboard and focus behavior. +- Cover normal, loading, empty, failed and successful states as relevant. Offer retry/cancel only when actually supported. +- Local prototype feedback is acceptable when clearly identified as disconnected from real services. Do not fabricate submission, payment or save success. +- Distinguish unfinished generation, partial delivery and editable outputs. Existing files do not mean the entire task is done. Link to real files and identify specific gaps. + +### 9. Author, inspect and repair + +1. **Read:** request, current project, type constraints, template guide and relevant layouts. +2. **Plan:** identify each page/section/scene's asset purpose, available files and gaps; query as required by section 7, then select or create structures. Explain key decisions briefly without requiring approval of internal layout IDs. +3. **Implement:** generate within existing authorization and model choices, save/place real content, preserve theme/runtime contracts and limit extensions to necessary changes. +4. **Programmatic checks:** use existing type/package validators for what they actually cover and record tool names and results. +5. **Real experience:** render at target canvas/viewport sizes; check reading, interaction, editing and requested formats. +6. **Local repair:** locate issues by page, element or timestamp; fix and retest affected areas. Shared CSS changes require checking every affected page. +7. **Deliver:** provide real artifacts and distinguish verified, unverified and unfinished work. + +Record asset verification separately from layout verification: purpose/gaps, actual required capability calls, reasons for generating or not generating, saved files and placement. Distinguish no generation needed, reuse, generated, unavailable authorization/tools, and query/generation failure. `unavailable` or `failed` is an accepted completion status when the file continues with a coherent fallback. Without call evidence, do not claim a query occurred or authorization is absent. A selected layout, valid HTML or verbal assertion cannot substitute for asset evidence. Keep records in the task, not additional user forms. + +Self-checks include representative short content, long Chinese titles and dense content; type rules determine exact cases. Source checks cannot substitute for missing rendering/export access. Preserve files, state limitations and tie repair cycles to observed failures rather than regenerating the whole artifact repeatedly. + +#### Executable verification and repair requirements + +- Before authoring, establish available preview, capture and export entry points. Prefer the client and supplied tools; if none is known, make one targeted environment check. Do not repeatedly scan the system or install browsers/dependencies to hide a verification gap. Continue independent work while marking visual acceptance unverified. +- Verify real content, final fonts and saved assets after fonts/images load. Record page/section/timestamp, observed issue, repair and recheck in the task's existing record; do not create a parallel project-file system. +- DOM bounds and resource checks identify candidates; screenshots establish reading quality. Neither excess `scrollHeight` nor successful package validation alone proves visual failure or success. Inspect title/body overlap, contrast on real backgrounds and obvious orphans in rendered output. +- Fix required issues directly when within authorization and scope. Do not deliver known defects as normal completed work. If repair conflicts with exact layout, fixed page count or theme-only scope, explain the concrete tradeoff and ask only about it. +- Re-render after every repair, using evidence from the latest files. Recheck all pages affected by shared-style changes. After two consecutive unsuccessful attempts at the same issue, choose a simpler suitable structure; if still blocked, preserve work and report it instead of looping or marking failure passed. +- Report content, structure, visual, editing and export results separately. Image generation success proves only the asset path; overlap means visual verification fails, and an unperformed export remains unverified. + +### 10. Acceptance levels and implementation status + +These are review categories, not claims of deployed automated enforcement. Preserve user files when reporting required repairs. + +| Level | Examples | Delivery treatment | +| --- | --- | --- | +| Must fix | Missing/fabricated essential content, obscured text, broken assets, necessary interaction/playback failure, flattened output when editability is required | Do not claim complete acceptance; repair or identify the blocker | +| Should fix | Unrequested theme drift, title orphans, inconsistent peer styles, unclear grouping, visibly uneven spacing | Repair and review; explain justified exceptions | +| Optional refinement | Nonessential decoration, rhythm or motion polish | Stay within style/scope and do not delay essential delivery | + +Actual automated coverage comes from service schemas, product validators and returned checks. Some package paths/fields, structures, variables and media timelines are checked; aesthetics, semantic completeness, Chinese line breaks and UX are not comprehensively automated. State conditions for screenshot, DOM and real-operation evidence. + +### 11. Type boundaries and acceptance + +Use the Design routing index to read only the active category. Existing PPT and Video workflows remain separate; shared principles do not impose one canvas or navigation model. + +| Category | Additional requirements | Acceptance evidence | +| --- | --- | --- | +| `slides` | Narrative, capacity, fixed canvas, editable objects and export | Every slide rendered; requested exports inspected | +| `site` | Responsive sections, semantics, navigation/forms and loading | Representative widths and working primary actions | +| `app` | Task flows, data density, controls and states | Main flow and relevant empty/error/recovery cases | +| `poster` | Target canvas, focal message, safe areas and resolution | Complete canvas at target size and requested export | +| `cards` | Sequence, per-card capacity and series consistency | Every card, correct order and requested export count | +| `report` | Evidence, charts/tables, hierarchy and pagination | Source/value checks, full report and requested print output | +| `article` | Reading rhythm, attribution and publishing compatibility | Full reading flow and actual target transfer when available | +| `other` | Explicit medium and capability contract | Relevant borrowed checks and stated format limitations | +| `video` | Pacing, timeline, narration/captions and synchronization | Key frames, seek/playback and requested exports | + +Rule coverage is not tested generation coverage. Validate representative real artifacts category by category, then feed cross-type findings into the shared source. A successful PPT does not prove another category's rendering, interactions or exports. Define scope, counterexamples and verification before expanding libraries. diff --git a/.agents/skills/ipollowork-presentations/references/slides-ppt.md b/.agents/skills/ipollowork-presentations/references/slides-ppt.md new file mode 100644 index 000000000..8ba82f21f --- /dev/null +++ b/.agents/skills/ipollowork-presentations/references/slides-ppt.md @@ -0,0 +1,136 @@ + + +# Slides and Native PPT Rules + +Applies to iPolloWork presentations and native editable PPT. Read the [shared guidelines](shared-guidelines.md) first. This reference adds PPT authoring and acceptance requirements; the selected mode, injected session contract and actual export capabilities remain implementation boundaries. For the ten reusable core-v1 structures, read the [layout guide](layout.md), then open only relevant source layouts. + +Status: authoring guidance, not proof of automatic injection into every engine or automated enforcement of every check. Do not claim experience or export verification without performing the relevant rendering and export checks. + +## 1. Determine task scope + +| Task | Allowed changes | Preserve | +| --- | --- | --- | +| Initial generation | Determine count/order from content; reuse, repeat, combine, remove or extend template patterns | Explicit constraints, visual identity, fixed canvas, runtime and editable contracts | +| Narrative rewrite or full redesign | Reorder, add/remove or rebuild pages within the request | Valid facts, assets, user edits and style not authorized to change | +| Targeted edit | Edit specified pages/objects and adjust layout within those pages when necessary | Unrelated pages, content, order and objects; shared CSS must not affect them | +| Theme-only change | Update semantic tokens and check real rendering | Page count/order, content, assets, canvas, object positions and editable markers | + +Initial generation does not inherit the template's sample count, narrative or brand data. If a theme change causes font overflow, first check font mappings and typography parameters. Explain any remaining conflict requiring object rearrangement rather than silently moving objects. Resolve exact-layout versus complete-content conflicts under the shared guidelines. + +## 2. Read the brief and plan the narrative + +- Read the current entry, confirmed requirements, existing pages, tokens, template guide and applicable layout index. Load only relevant candidates. +- Identify audience, purpose, language, setting, main conclusion, evidence and delivery format from existing materials. Proceed when sufficient; ask only about consequential gaps. +- Content and explicit user constraints determine page count. Speaking time can inform pacing, not a fixed minutes-per-slide quota. Examples and capacity hints are not hard page-count requirements. +- Plan each page's message, content relationship, evidence and asset purpose. Check reusable assets and gaps, query capabilities under the shared rules, then select or create a layout. This plan guides execution; do not require approval of internal IDs or an outline unless the user requests it. +- Give each slide one main reading task. Prefer headings that state a conclusion or question, supported by evidence. Use section pages when useful, not mandatory agenda, transition or thank-you pages merely to fill a formula. +- Separate facts, assumptions and missing information. Replace/remove example figures, logos and testimonials rather than presenting them as real user outcomes. + +## 3. Select and extend layouts + +Select structure by content relationship, then map it to the active visual language. The following are selection criteria, not a claim that every pattern is installed. + +| Relationship | Consider | Check | +| --- | --- | --- | +| Statement, opening or chapter | A strong heading with one meaningful visual | Clear emphasis without decorative filler | +| Comparing options | Aligned columns or a comparison table | Common dimensions; adjust proportions for uneven content | +| Steps, development or stages | Process, timeline or phase structure | Clear order and connections, not unordered cards | +| Data or evidence | Key metrics, charts, tables and sources | Units, definitions, period, axes and conclusion agree | +| Case study or audience | Lead case with evidence, or suitable profile structure | A concrete subject, not generic copy with renamed people | +| Principles, capabilities or summary | Peer items or a hierarchy | Genuine peer relationships; do not flatten a hierarchy | + +- Prefer suitable local or shared patterns. Read their real source and CSS dependencies rather than guessing from filenames. +- Copy only selected structural fragments and local styles, bound to current theme tokens. Omit preview hosts, scripts, default palettes and fonts. +- Replace content before adjusting columns, proportions, image/text areas and optional slots. If none fits, extend with the active typography, graphic and spacing language; do not replace the theme. +- Repeating a pattern is useful for comparable cases or data. Avoid mechanical repetition without a content reason, but do not force adjacent pages to differ. +- Maintain valid unique page/object identifiers and order, retaining recognized `data-ipw-slide` roots. +- Shared catalog, local source and new layouts are all valid sources. A local pattern absent from the global catalog is not a violation. Give new structures meaningful `data-layout` IDs and describe their relationship, slots and capacity in the page plan. Global registration or `data-layout-origin="extension"` is not a prerequisite. Do not automatically add a one-off layout to the global library or call it verified. +- Fixed-canvas extensions must not use viewport reflow or off-canvas clipping to conceal overflow. Adjust structure, remove empty slots or split pages. A negative local offset alone is not failure; inspect actual text/shape bounds and editable export behavior. + +## 4. Capacity and Chinese typography + +- Retain the supported fixed 16:9 canvas; do not add mobile stacking or breakpoint reflow. Check product support before adopting another requested ratio. +- Use coherent roles for headings, body, notes and sources. Choose sizes, leading and whitespace for the template and viewing scale, not chat typography or a generic website scale. +- For dense content, tighten nonessential wording, adjust space or choose another structure; split if page constraints permit. Do not shrink all text, compress leading, clip content or omit essential facts to force a fit. +- Inspect long Chinese titles for semantic breaks, glyph collisions, orphans and distance from body text. `text-wrap: balance` is only an aid. Check font fallback, values/units and long Latin words in mixed text. +- Charts must be readable at presentation scale, with visible sources and necessary notes. Do not encode important distinctions with color alone. +- Review reading order among title, body, image and source, and consistency of margins/density across pages. No overflow does not imply good layout. + +### Capacity planning and overflow handling + +For each selected pattern, identify the content relationship, real source, title/body areas, available line capacity with the current font, image ratio, allowed variants and overflow response. Use an existing catalog entry when available; otherwise measure the source and record findings in the current page plan. Do not invent verified limits or create a separate library for one generation task. + +Capacity depends on actual font, size, leading and space, not a universal Chinese-character count. Trial the longest title and densest page first. If a narrow-column title exceeds its planned lines, reallocate space or change structure; do not leave body text at a fixed start that collides with it. With no existing typography specification, a 1280×720 trial baseline is 40–56px headings, 24–30px body and supporting text at least 18px; scale proportionally for other canvases. These are starting points requiring visual review, not overrides of user/template standards or permission to shrink long copy. + +Existing Brand Narrative patterns provide these planning starting points, not multilingual hard limits: + +| Source | Suitable content and slots | Capacity response | +| --- | --- | --- | +| `.manifesto` | One statement, support paragraph and visual | Trial 2–3 title lines; widen or stack regions before support text collides | +| `.tension` | Two sides compared on common dimensions | Short heading/evidence per side; adjust proportions, use a table or split for multiple dimensions | +| `.audience-collage` | A few audience/person keywords and explanations | Scattered keywords cannot hold long narratives; use ordered image/text regions for longer descriptions | +| `.positioning` | Two justified dimensions and positions | Short readable axis labels with separate explanation; do not force literary narrative into a positioning map | +| `.voice-spectrum` | Peer principles and brief explanations | Check each real column width; reduce columns or split rather than shrinking all text | +| `.expression` | Lead case and supporting content | Clear primary/secondary slots; review real image crops; move excess evidence to another page | + +Custom work uses the same capacity rules. Establish a coherent visual language before selecting structures; extend when none fits. Custom does not mean designing every page arbitrarily from scratch, and shared preview colors/fonts do not replace the chosen theme. + +### Contrast and line-break review + +- Check actual backgrounds behind text, including photos, gradients, color edges and overlays. Target at least 4.5:1 for normal text and 3:1 for large text. Large means at least 24px regular or about 19px bold at actual display scale, not a magnified screenshot. Check the least favorable image region; move text or add a theme-consistent stable backing when needed. Comparing token values alone is insufficient. +- Break Chinese headings semantically and avoid body endings with only 1–2 characters or punctuation. Adjust text width, remove unsuitable hard breaks or change layout before tightening wording without losing meaning/facts. Preserve verbatim copy when requested. Do not shrink the whole slide to eliminate orphans. +- Title, body and notes need distinct regions that fit their real content. Inspect rendered line boxes and following regions; overflowing fixed-height titles must not cover body text. Deliberate layering is acceptable, unreadable text is not. + +## 5. Theme and assets + +Native editable PPT can contain `data-pptx-image` objects. Editability covers supported properties such as position and size; every image pixel need not become a vector object. Do not omit appropriate imagery to guarantee editability. If multiple suitable models require a choice, ask once before committing any image-dependent page; continue independent layout work only with the asset marked pending, and never silently use `defaultModel` or downgrade to shapes merely to avoid the question. + +- Retain a selected template's visual identity unless restyling is explicitly requested; a changed audience alone is not authorization. +- Use current semantic tokens and preserve the `design-tokens.css` contract. Do not restore sample colors, add inline theme overrides or import another global theme. +- Follow the shared asset-selection, authorization, model-choice, cost and failure rules. Do not require a model selection for every routine generation call. +- Apply the shared visual-purpose decisions during page planning; no separate per-slide assessment report is required. Proactively supplement imagery that improves understanding or atmosphere, reuse adequate assets, and keep data/process/architecture diagrams editable. Pure decoration does not require generation. No fixed image quota applies; generated illustrations cannot replace real evidence. +- Visual slots can contain images, editable charts or shapes. Sample geometry is not a fixed asset requirement. Use `data-pptx-image` when replacing a slot with an image and adjust its container/crop. Missing image slots or editable-output goals do not cancel a legitimate asset need. +- Check resolution, crop, proportion and image/text relationships. HTML playback does not establish media support in the requested PPT format; verify actual export support before embedding. +- Save files/assets in the current `design//` and reuse existing asset directories; do not create a parallel project. + +## 6. Editing, playback, notes and motion by mode + +### Native Editable PPT + +- Preserve supported `data-pptx-text`, `data-pptx-shape` and `data-pptx-image` markers on objects that need editable export, following the injected visible-object coverage contract. +- Give each element one PPTX object type. A text card uses a shape container and separate marked text children, not shape/text markers on the same node. Check exported text per page; object counts alone do not prove completeness. +- Use explicit supported shape nodes for meaningful decoration, not unmarked pseudo-elements. Browser visibility does not prove PPTX inclusion. +- Keep object geometry simple and measurable. Do not assume lossless export of complex DOM/CSS, or flatten editable text/shapes/pages into screenshots. +- The Design panel owns navigation. Do not add scripts, keyboard handlers, page controls, navigation buttons or speaker-note nodes, and do not transplant OpenDesign's runtime. +- Do not add animation frameworks or promise PPTX animation retention by default. Verify support for requested effects, explaining unsupported cases and feasible alternatives. +- Use actual supported notes functionality. If notes cannot be embedded, provide a separate script when requested and state that it is not inside the PPTX. + +### HTML Presentation + +- Retain the template's supported fixed canvas, keyboard navigation, controls and notes contract; do not add a second runtime. +- Add speaker notes only when supported and needed. Keep presenter guidance separate from audience-visible content. +- Use existing motion to explain sequence/emphasis, usually with one clear focus per page; do not animate everything mechanically. Verify navigation, replay and screenshots do not leave content invisible. +- Working HTML playback is not verified editable PPTX export. Identify the actual delivered format. + +## 7. Generation and acceptance loop + +Follow read → asset assessment and required capability queries → page planning and layout selection/extension → asset generation, saving and placement → inspect/repair → deliver. + +1. **Content:** compare the page plan with user materials; verify narrative, facts, units, sources and essential conditions. Replace sample content and list required gaps. +2. **Structure:** use existing validators for fixed canvas, slide roots, identifiers, resource references and marker coverage. Template-package acceptance follows the shared contract separately and does not replace artifact-experience checks. Distinguish shared reuse, local reuse and extensions instead of enforcing a global ID whitelist. Positioning/overflow checks identify candidates; actual clipping, obstruction, canvas violations or lost editability justify repairs. + **Assets:** verify decisions, actual required queries, generated/reused results and actual references. Replacing absent source photos with geometry without required queries leaves the media workflow incomplete. Prefer editable data/process diagrams; do not accept or reject by image count. +3. **Deck overview:** inspect all thumbnails for visual consistency, density and narrative rhythm. Repeated patterns need a content reason. +4. **Every-slide rendering:** wait for fonts/assets and inspect every page at target size, not just the cover or a sample. Focus on long Chinese titles, dense pages, charts and new layouts for overlap, overflow, orphans, crop and contrast. Preview-only page switching must not alter the output runtime contract. Standalone HTML captures do not replace client navigation checks. +5. **Client experience:** actually navigate the appropriate editor and exercise affected capabilities. For native PPT, verify representative text, shape and image edits; for HTML, verify navigation and affected notes/motion. +6. **Requested export:** use the supported product path and inspect actual PPTX/PDF/image files when requested. PPTX needs both visual and editability checks; markers, filenames or HTML captures alone prove neither. Export entry points must be discoverable and callable. If no model-callable client export exists, preserve editable source and direct the user accurately to client export. Do not blindly scan/install tools or reconstruct approximate layouts as a substitute for native export. Use standalone PPTX generation only when explicitly requested and verify it separately. +7. **Repair and recheck:** follow the shared executable repair loop. Locate issues per page, repair locally and capture again using the latest files. Fix obscured/unreadable content before orphans, spacing and rhythm. Recheck every page affected by shared-style changes; do not repeatedly regenerate the whole deck without cause. + +If client, rendering or export access is missing, preserve artifacts and distinguish checked, unverified and unfinished work. Source checks are not real-experience verification. Essential missing content, broken resources, obstruction or lost required editability are must-fix issues under the shared rules. + +Deliver the current entry, actual completed exports and a short explanation. Never list unperformed exports as results. Nontechnical users do not need internal layout IDs, object markers or complete validation logs. + +## References and maintenance + +OpenDesign's [PPT authoring workflow](https://github.com/nexu-io/open-design/blob/main/design-templates/html-ppt/references/authoring-guide.md) and [PPT Skill](https://github.com/nexu-io/open-design/blob/main/design-templates/html-ppt/SKILL.md) informed requirements gathering, theme/layout separation, page-level authoring and browser review. These rules are rewritten for iPolloWork's native editing, theme and export constraints; they do not copy template code or runtime. + +Maintain cross-type principles in the shared contract and PPT-specific rules here. The [layout guide](layout.md) describes reusable core-v1 structures; template-local patterns belong in `authoring.md`. OpenDesign's mandatory adjacent-layout changes, fixed speaking/page-count suggestions, presentation runtime and decorative animation requirements are not iPolloWork defaults. Automatic injection and real-model execution require separate verification; updated documents alone do not prove every engine follows them. diff --git a/.agents/skills/ipollowork-video-studio/SKILL.md b/.agents/skills/ipollowork-video-studio/SKILL.md index c2a5abb23..7c0b43b36 100644 --- a/.agents/skills/ipollowork-video-studio/SKILL.md +++ b/.agents/skills/ipollowork-video-studio/SKILL.md @@ -7,6 +7,10 @@ description: Create or edit the HyperFrames project owned by an active iPolloWor Use this Skill only for the video project owned by the active iPolloWork session. The built-in Video Studio, timeline, preview, templates, and HyperFrames runtime exist independently of this Skill. +Before editing, read [references/shared-guidelines.md](references/shared-guidelines.md), then [references/video.md](references/video.md). Shared rules own content/media decisions; the video reference owns scene, timing, playback and acceptance constraints. + +Before initial/full authoring, call `media/artifact_media_review` phase=plan with the active HTML sourcePath and visual needs; follow references/shared-guidelines.md. Before final delivery call phase=check, resolve pending/missing assets and disclose fallbacks. The host queries capabilities and checks saved-file placement and generation receipts; preview remains required. Do not replace this workflow with a verbal assessment or a self-selected geometric style. + ## Session contract - Treat the active session's injected Video task contract, project directory, Studio port, and exact `index.html` path as authoritative. @@ -24,3 +28,11 @@ Use this Skill only for the video project owned by the active iPolloWork session 6. Run the HyperFrames check required by the active session against that exact project before reporting completion. If the active session provides stricter timing, template, media, or validation instructions, those instructions take precedence. + +## Content-led layout adaptation + +Follow the injected template layout contract. Extract the template's typography, palette, spacing, graphic primitives and motion vocabulary. Choose scene compositions for their content: a comparison, sequence, data explanation, case study or key message. Reuse a fitting scene, vary its composition, or build a new scene from the same primitives instead of repeating the template's text placeholders. Keep transitions and movement stylistically consistent; new layouts must retain deterministic timing and editor hooks. + +Respect explicit exact-layout requests, fixed-brand regions and the scope of follow-up edits. Inspect representative frames and transitions for readability, density, clipping, unjustified repetition and style drift. Allow enough time for the actual narration and synchronize the timeline after changes; do not shrink text, drop facts or accelerate narration to fit sample geometry or timing. + +Video sessions receive `core-v1-index.md` and `core-v1-video/` by default. Read the index, then this type's catalog, layout guide and shared contract. Reuse fitting scene bodies with scoped styles; do not copy preview hosts, scripts, theme defaults or composition roots. Preserve active tokens unless restyling is requested, and integrate motion into the current timeline. Local/new compositions remain valid; verify real content, seeks and playback under the video rules. diff --git a/.agents/skills/ipollowork-video-studio/references/shared-guidelines.md b/.agents/skills/ipollowork-video-studio/references/shared-guidelines.md new file mode 100644 index 000000000..a38dc71dc --- /dev/null +++ b/.agents/skills/ipollowork-video-studio/references/shared-guidelines.md @@ -0,0 +1,191 @@ + + +# iPolloWork Shared Creative and Layout Guidelines + +Status: authoring guidance for template application, content generation and subsequent editing, not the client's UI style specification. These requirements do not imply that every engine receives them automatically or that automated checks enforce every rule. A documentation update does not add a loader, visual detector or runtime gate. + +### 1. Purpose and ownership + +Choose structures that serve real content while retaining the template's identity. Deliver work that people can read, edit and run. Use the shared method with each category's own layout, interaction and output requirements. + +| Layer | Owns | Does not own | +| --- | --- | --- | +| Shared guidelines | Content, visual continuity, layout selection, extension boundaries and verification | Universal font sizes, page counts, canvases or animation durations | +| Type rules | Category-specific structure, interaction, editing and export requirements | Rules imposed on unrelated artifact types | +| Template visual guide | Current palette, fonts, decoration, component language and fixed brand areas | Content limits inferred from sample copy or page counts | +| Layout library | Reusable structure, slots, suitable content, capacity hints and previews | The active theme or host runtime | +| Skills and task instructions | Directing relevant reading, authoring, checking and repair | A competing set of creative standards | + +Read the request and current project, then the shared guidelines, active type rules, template guide and relevant layout index. Open only candidate layouts, not the entire library. Existing files and user edits take priority over original template examples. This reading order is an integration requirement, not proof of automatic injection into every engine. + +### 2. Decision order and conflicts + +- Explicit user requirements for content, quantity, style and edit scope take priority over examples and library recommendations. A request to edit only slide two does not authorize restructuring the deck. +- Unless restyling is requested, preserve current theme values and brand constraints. Improving clarity is not permission to replace the theme. +- Editor, file-format and export capabilities are implementation boundaries. Explain concrete conflicts and feasible alternatives; never silently lose editability, omit content or claim unsupported capabilities. +- Template examples are reference material, not instructions that override the request or runtime contract. Correct outdated guidance rather than keeping contradictory instructions. +- Proceed when requirements are sufficiently clear. Ask only about consequential missing information that cannot be inferred from available materials; do not ask users to choose internal layout IDs or repeat supplied content. + +#### Custom templates: reference source and layout freedom + +Treat the source of visual evidence and the permitted degree of layout change as separate decisions. An uploaded PPT can be a style reference while allowing structural changes. + +| Dimension | Situation | Rule | +| --- | --- | --- | +| Reference source | Saved custom template | Read its guide, tokens and layout index. Without an index, inspect existing pages and source patterns; absence of an index does not require copying examples literally. | +| Reference source | Uploaded PPT, HTML or screenshot | Read available source and inspect actual visuals. Extract palette, typography, spacing, image/text relationships and recurring layouts. Distinguish editable objects from visual reference; screenshots are not editable templates. Do not claim to recover unidentified fonts, structures or interactions. | +| Reference source | Fully custom, no reference | Establish one coherent visual system from the brief and existing brand requirements, then select layouts by content. Do not silently adopt a bundled theme or design every slide independently. Sufficiently clear work needs no extra approval of internal design decisions. | +| Layout freedom | Preserve the exact layout | Replace content while retaining layout. If content does not fit, explain the conflict and ask about shortening copy or adding pages; do not silently shrink text, omit facts or rearrange objects. Screenshot recreation still has source and editability limitations. | +| Layout freedom | Retain style, adapt layout | Preserve visual identity while reusing, combining or extending structures. Shared layouts must not introduce another palette, font system or runtime. | + +Default template application retains style while adapting structure to content. Exact-layout mode applies only when explicitly requested or already agreed. Preserve prior choices without asking again; clarify only ambiguity that materially affects the result. Targeted edits protect unrelated pages and objects. Theme-only edits preserve content and geometry; the default freedom does not expand either scope. + +Sample copy, page counts, data and assets are not automatically user requirements or verified facts. Check the active import, editing and export path: editable objects in the source file do not prove that the current importer preserves them. Disclose unsupported or unreadable parts; do not present flat screenshots as editable delivery. + +Acceptance must distinguish saved templates without indexes, editable uploads, screenshot-only references and custom work without references, as well as exact-layout versus adaptive modes. Claim verification only for combinations actually exercised; bundled-template tests do not prove all custom-template cases. + +### 3. Content before structure + +Identify audience, purpose, main message, supporting material and intended action before organizing pages, sections or scenes. + +- Content determines page count, scene count and duration. Examples are not quotas. Only explicit user quantities constrain the result; distinguish approximate targets from strict limits. +- Separate facts, goals, assumptions and unresolved information. Never invent data, sources, testimonials, customer logos, prices or outcomes to fill a layout. +- Preserve important facts, conditions, units and source relationships. Tighten wording without removing qualifications or evidence merely to fit. +- An empty slot may mean the structure is unsuitable. Remove unnecessary slots or change layout instead of padding with meaningless copy. +- Produce actual files when information is sufficient. If confirmation is necessary, pause only dependent work. A confirmed video script does not need the same approval again. + +### 4. Preserve visual identity + +- Retain the current palette, typography, radii, decoration and overall character by default. A new topic or audience does not authorize a brand redesign. +- Use current semantic `--ipw-*` tokens. Keep structural CSS separate from theme values; do not create another theme in inline styles or scripts. Follow the Design-System Layer contract below where applicable. +- Shared layouts supply structure and capacity guidance. Map them to the active visual language; omit preview palettes, fonts, hosts and demo scripts. +- Preserve proportions of logos, icons and photos. Keep fixed brand areas; update editable brand slots from user content. Demo logos are not customer endorsements. +- Do not categorically reject particular colors, serif fonts, gradients or symmetry. Judge readability, template intent and user requirements rather than imposing a universal aesthetic. +- Theme changes must not rewrite content, replace images or reorder pages. Check actual typography after font changes to catch new overflow. + +### 5. Select and extend layouts + +Identify the content relationship: statement, comparison, process, data, case study, hierarchy or summary. Compare local and shared patterns and prefer a suitable structure that retains the style; neither source has unconditional priority. + +The catalog is a preferred reuse source, not an ID whitelist or a complete inventory of extracted templates. Local source patterns remain valid even when absent from the global catalog. When none fits, write a new layout within the current visual language and record its origin, relationship, slots and capacity in the page plan. A new ID, missing global registration or missing provenance attribute is not grounds for rejection. Validate content fit, rendered layout and type contracts. Do not label a one-off extension as a verified library pattern; admission requires separate real-content, client-preview and applicable export checks. + +| Situation | Action | +| --- | --- | +| Relationship and capacity fit | Reuse, replace content and check actual rendering | +| Relationship fits; capacity differs slightly | Adjust columns, proportions, alignment, image/text area or optional slots | +| Relationship does not fit | Select another pattern; do not force a sequence into unordered cards | +| No suitable existing structure | Extend with the current template's visual elements and retain the type runtime contract | +| Exact layout is required but content will not fit | Explain the conflict and offer copy reduction or additional pages/scenes; do not omit content without permission | + +Extension is not a theme change. Scope new CSS locally so one edit does not affect unrelated pages. Repeat structures when comparison benefits from consistency; do not force variety or turn everything into the same card simply for convenience. + +Capacity is a selection hint, not a hard limit on user content. First tighten nonessential wording, then adjust space, choose a better structure or split within user constraints. Do not default to shrinking all text, compressing line height or clipping important content. + +Fixed-canvas presentations retain the established aspect ratio and coordinate system. Do not use negative positioning, viewport-dependent `@media`/`@container` reflow or off-canvas hiding as overflow workarounds. Adjust structure, remove unused slots or redistribute content. `overflow: hidden` may define the canvas boundary, never conceal titles, body text or editable objects. An intentional local offset must be judged by actual bounds and output, not rejected solely because it is negative. + +### 6. Hierarchy, spacing and Chinese typography + +Each reading region should make the entry point, grouping and next step clear. Establish hierarchy through size, weight, position, whitespace and color without forcing every region into an identical heading scale. + +- Keep roles consistent: peer headings, body copy, captions and data labels need coherent styles. Equal relationships use equal spacing; different relationships may use different spacing. +- Clearly associate headings with body copy, charts with captions, and values with units. Check both crowding and gaps that interrupt the reading relationship. +- Multiline Chinese titles must not inherit tight English leading or negative tracking blindly. Check the actual font, weight and canvas for glyph collisions; handle mixed scripts locally. +- Avoid short last lines consisting of a lone Chinese character and punctuation. Break at meaningful boundaries. `text-wrap: balance` helps but cannot replace screenshot review or guarantee intact phrases. +- Hard breaks that work on desktop may create orphans on narrow websites; check breakpoints. Do not convert a fixed PPT canvas into vertically stacked web content. +- Keep values, units, headers and notes aligned. Do not clip chart labels. Choose text sizes by artifact type, viewing distance and template rules; the client's 14px chat text is not a PPT or video body-text standard. +- Inspect reading rhythm and density visually as well as geometrically. Staying inside bounds does not establish good layout. + +### 7. Color, media and motion + +- Use color consistently for hierarchy, brand or state. Important distinctions must not rely on color alone. Check text, controls and charts against actual backgrounds; type rules define applicable contrast targets. +- Emphasis serves content. Do not impose arbitrary accent-color quotas or add glows, icons, cards and backgrounds foreign to the template language. +- Motion should support sequence, feedback or narrative. Website interaction and video storytelling do not share one fixed-duration rule. Reduced-motion interaction preferences must not silently rewrite an exported video's timeline. +- Video uses its supported deterministic timeline so seeking, playback and export agree. Web animation must not block reading or interaction and should support reduced motion where appropriate. Static deliverables need no decorative animation merely to demonstrate capability. + +#### Asset selection, authorization and generation + +This workflow applies to all Design categories and video. Shared guidance decides when assets are useful, when user input is needed and what delivery requires. The media workbench plugin and corresponding Skills own capability queries, model parameters, submission, job status and result placement; type rules must not implement competing call flows. + +For initial creation and full redesign, decide useful visuals **before choosing layouts**. Scene, story, place, people, product and cover content normally merits image consideration; data/process/architecture normally merits editable diagrams. Suitable existing assets should be reused. Images need not be indispensable, and there is no image quota. A text-only attachment, an imageless catalog example, editable PPT mode or a self-chosen geometric style is not a reason to skip imagery. An illustration may evoke autumn or explain a warehouse scenario; label it as illustrative and never claim it is documentary evidence. + +Use one three-step workflow for template application and custom creation: + +1. **Plan and query.** Discover `media/artifact_media_review` through the host extension tools and call `phase="plan"` before layout. Pass the active workspace-relative HTML `sourcePath` and concise `needs` (`id`, `purpose`, `kind`: `image`, `video`, `reuse` or `diagram`). The host records the plan in the existing `brief.json` and performs live capability queries for image/video needs. Read the returned capabilities; plugin installation or a chat model name is not proof of media authorization. Do not write a separate assessment document. An empty plan requires a specific exemption (`explicit-text-only`, `no-generation`, `local-edit`, `theme-only`, `existing-assets` or `diagrams-sufficient`) and reason grounded in the user's scope and content. Do not use diagrams-sufficient merely because shapes can be drawn. Reuse needs still require delivery placement checks. Keep existing planned needs across retries. +2. **Resolve and produce.** Use the model-selection table below, then the image-generation/media-use Skill for actual generation, saving and insertion. Do not ask for per-page approval or another generation confirmation within authorized scope. Preserve real evidence, relevant existing files, and scope/cost constraints. Call job status/recovery for uncertain submissions before retrying. A submitted request is not a saved asset. Save to the current project's `assets/` and use relative URLs. If capability querying, authorization or generation fails, continue independent file work with a coherent fallback and report the specific limitation; do not open settings or wait for authorization. If the user still needs to choose a model, keep the image pending rather than quietly abandoning it. +3. **Check before delivery.** Call `media/artifact_media_review` with `phase="check"`, the same `sourcePath`, and one outcome per planned id. Use `generated`/`reused` with a project-relative `path`; a generated copy also includes the original workspace-relative `generationPath` returned by the tool. The host verifies nonempty files, HTML/CSS references and actual session generation receipts. Use `diagram` only for a planned diagram. Pending or missing items must be resolved; a second empty plan or geometric replacement does not satisfy a planned image. `declined`, `unavailable` and `failed` require specific reasons and are reported partial media delivery, not successful generation. Preserve the actual tool/user evidence; the validator does not independently prove consent, authorization failure or relevance. Independently preview the final result to check cropping, visibility, meaning and playback. If the host review action itself is unavailable, disclose that verification gap rather than claiming it ran. + +| Model condition | Action | +| --- | --- | +| User explicitly selected an available, suitable model | Use it; preserve the choice within the task | +| Explicit model unavailable or unsuitable | Explain and ask before substituting unless alternatives were authorized; continue independent work | +| No explicit model; verified suitable saved preference or approved automatic-selection policy | Follow it within scope and cost settings | +| Exactly one suitable authorized model and no preference | Use it within scope | +| Multiple suitable models and no preference/policy | Ask once before image-dependent pages; keep the asset pending and continue independent work. Do not silently choose `defaultModel` or replace imagery with shapes | +| No authorized suitable model | Continue the file with reuse or a coherent editable fallback and report the unavailable asset; do not guide to settings | +| Query failed | Report capability as unknown, not unauthorized; continue with a disclosed fallback | + +The API's `defaultModel` is a computed candidate, not a saved preference. Save preferences only on explicit request when supported. Recheck capability when the model, operation, parameters or authorization changes, or an error requires it. Never request keys in chat or invent prices, budgets or authorization state. + +The catalog owns structural relationships and reusable fragments, not media policy. Adapt a fitting layout to a useful asset; write a new composition when needed. Type rules add only medium-specific constraints: fixed canvas/editable objects for PPT, responsive loading for web, source evidence for reports, and timing/synchronization for video. Completion checks must exercise the actual query → selection → generation → saved file → insertion path; valid HTML or installed rules alone do not prove it. + +### 8. Interaction and artifact state, where applicable + +Apply this section only to interactive artifacts or regions. Static PPT pages do not need unrelated forms or queues. + +- Buttons, links and menus need real destinations and appropriate pointer, keyboard and focus behavior. +- Cover normal, loading, empty, failed and successful states as relevant. Offer retry/cancel only when actually supported. +- Local prototype feedback is acceptable when clearly identified as disconnected from real services. Do not fabricate submission, payment or save success. +- Distinguish unfinished generation, partial delivery and editable outputs. Existing files do not mean the entire task is done. Link to real files and identify specific gaps. + +### 9. Author, inspect and repair + +1. **Read:** request, current project, type constraints, template guide and relevant layouts. +2. **Plan:** identify each page/section/scene's asset purpose, available files and gaps; query as required by section 7, then select or create structures. Explain key decisions briefly without requiring approval of internal layout IDs. +3. **Implement:** generate within existing authorization and model choices, save/place real content, preserve theme/runtime contracts and limit extensions to necessary changes. +4. **Programmatic checks:** use existing type/package validators for what they actually cover and record tool names and results. +5. **Real experience:** render at target canvas/viewport sizes; check reading, interaction, editing and requested formats. +6. **Local repair:** locate issues by page, element or timestamp; fix and retest affected areas. Shared CSS changes require checking every affected page. +7. **Deliver:** provide real artifacts and distinguish verified, unverified and unfinished work. + +Record asset verification separately from layout verification: purpose/gaps, actual required capability calls, reasons for generating or not generating, saved files and placement. Distinguish no generation needed, reuse, generated, unavailable authorization/tools, and query/generation failure. `unavailable` or `failed` is an accepted completion status when the file continues with a coherent fallback. Without call evidence, do not claim a query occurred or authorization is absent. A selected layout, valid HTML or verbal assertion cannot substitute for asset evidence. Keep records in the task, not additional user forms. + +Self-checks include representative short content, long Chinese titles and dense content; type rules determine exact cases. Source checks cannot substitute for missing rendering/export access. Preserve files, state limitations and tie repair cycles to observed failures rather than regenerating the whole artifact repeatedly. + +#### Executable verification and repair requirements + +- Before authoring, establish available preview, capture and export entry points. Prefer the client and supplied tools; if none is known, make one targeted environment check. Do not repeatedly scan the system or install browsers/dependencies to hide a verification gap. Continue independent work while marking visual acceptance unverified. +- Verify real content, final fonts and saved assets after fonts/images load. Record page/section/timestamp, observed issue, repair and recheck in the task's existing record; do not create a parallel project-file system. +- DOM bounds and resource checks identify candidates; screenshots establish reading quality. Neither excess `scrollHeight` nor successful package validation alone proves visual failure or success. Inspect title/body overlap, contrast on real backgrounds and obvious orphans in rendered output. +- Fix required issues directly when within authorization and scope. Do not deliver known defects as normal completed work. If repair conflicts with exact layout, fixed page count or theme-only scope, explain the concrete tradeoff and ask only about it. +- Re-render after every repair, using evidence from the latest files. Recheck all pages affected by shared-style changes. After two consecutive unsuccessful attempts at the same issue, choose a simpler suitable structure; if still blocked, preserve work and report it instead of looping or marking failure passed. +- Report content, structure, visual, editing and export results separately. Image generation success proves only the asset path; overlap means visual verification fails, and an unperformed export remains unverified. + +### 10. Acceptance levels and implementation status + +These are review categories, not claims of deployed automated enforcement. Preserve user files when reporting required repairs. + +| Level | Examples | Delivery treatment | +| --- | --- | --- | +| Must fix | Missing/fabricated essential content, obscured text, broken assets, necessary interaction/playback failure, flattened output when editability is required | Do not claim complete acceptance; repair or identify the blocker | +| Should fix | Unrequested theme drift, title orphans, inconsistent peer styles, unclear grouping, visibly uneven spacing | Repair and review; explain justified exceptions | +| Optional refinement | Nonessential decoration, rhythm or motion polish | Stay within style/scope and do not delay essential delivery | + +Actual automated coverage comes from service schemas, product validators and returned checks. Some package paths/fields, structures, variables and media timelines are checked; aesthetics, semantic completeness, Chinese line breaks and UX are not comprehensively automated. State conditions for screenshot, DOM and real-operation evidence. + +### 11. Type boundaries and acceptance + +Use the Design routing index to read only the active category. Existing PPT and Video workflows remain separate; shared principles do not impose one canvas or navigation model. + +| Category | Additional requirements | Acceptance evidence | +| --- | --- | --- | +| `slides` | Narrative, capacity, fixed canvas, editable objects and export | Every slide rendered; requested exports inspected | +| `site` | Responsive sections, semantics, navigation/forms and loading | Representative widths and working primary actions | +| `app` | Task flows, data density, controls and states | Main flow and relevant empty/error/recovery cases | +| `poster` | Target canvas, focal message, safe areas and resolution | Complete canvas at target size and requested export | +| `cards` | Sequence, per-card capacity and series consistency | Every card, correct order and requested export count | +| `report` | Evidence, charts/tables, hierarchy and pagination | Source/value checks, full report and requested print output | +| `article` | Reading rhythm, attribution and publishing compatibility | Full reading flow and actual target transfer when available | +| `other` | Explicit medium and capability contract | Relevant borrowed checks and stated format limitations | +| `video` | Pacing, timeline, narration/captions and synchronization | Key frames, seek/playback and requested exports | + +Rule coverage is not tested generation coverage. Validate representative real artifacts category by category, then feed cross-type findings into the shared source. A successful PPT does not prove another category's rendering, interactions or exports. Define scope, counterexamples and verification before expanding libraries. diff --git a/.agents/skills/ipollowork-video-studio/references/video.md b/.agents/skills/ipollowork-video-studio/references/video.md new file mode 100644 index 000000000..eb7c0f088 --- /dev/null +++ b/.agents/skills/ipollowork-video-studio/references/video.md @@ -0,0 +1,40 @@ + + +# HyperFrames Video Rules + +Use for `video`, including template application, custom generation and targeted edits. Read the [shared guidelines](shared-guidelines.md) first. The active session's exact project, runtime, media actions and editor contract are authoritative. + +## Plan content and reuse + +Read the confirmed brief/storyboard, current `index.html`, template guide, tokens and existing assets. Respect already confirmed choices. Content determines scene count and timing; sample counts and durations are not quotas. An explicit user maximum remains strict. For targeted edits, preserve unrelated scenes, media and user changes. + +Read `core-v1-index.md` beside `brief.json`, then `core-v1-video/catalog.md`, `layout.md` and `shared-contract.md`. Match content relationships and compare global with local compositions. Reuse fitting scene bodies or write a new composition in the active visual language. If references are absent in an older session, inspect actual local files instead of inventing paths or overwriting the user's project. + +Video layouts describe spatial content slots, not complete compositions, timelines, narration or required scene duration. Never import PPT page roots or website responsive behavior into a video scene. + +## Composition and timing + +- Keep one authoritative root composition, its identity, declared stage dimensions and registered timeline. Use unique scene/clip IDs and supported editor hooks. +- When adding, removing, reordering or retiming scenes, synchronize the root duration, scene windows, clips, transitions, captions, audio and animation timestamps. Preserve these values for theme-only or unrelated edits. +- Use the session's FPS and frame-aligned timing rules; retain required numeric precision in serialized seconds. Sample reading time is planning input, never a replacement for measured audio. +- Drive movement through the existing paused, registered GSAP/HyperFrames timeline. Ensure direct seeking and replay are deterministic; no ambient CSS loops, wall-clock timers, random values or independently running timelines. +- Scope animation selectors to the actual scene instance. Fit entrance, readable hold and exit inside the scene window; transition overlaps must not obscure required information. +- Keep playback and audio sequencing framework-owned. Do not mute tracks or replace narration/music merely to avoid a preview problem. + +## Visuals, assets and narration + +The template owns typography, palette, graphic language and motion style. Apply theme tokens to scene styling; keep timing/tracks outside `design-tokens.css`. Compose for the declared stage and aspect ratio; change geometry intentionally for a different target, never through viewport-dependent reflow. + +Follow shared asset/model rules and the active image/video generation Skills. Assess useful imagery with the storyboard; a catalog placeholder is not a reason to omit useful media. Reuse available files, query capabilities, resolve model choice within the authorized scope, and save new files under the current project's `assets/`. For asynchronous generation, resolve status/recovery before duplicate submission and use only saved valid media. + +Follow `ipollowork-video-voiceover` and the injected voiceover contract for enablement, authorized/default voices and validation. Preserve an explicit disabled choice. Without authorized narration, continue visual work and report its absence. Never treat a missing voice selection as no authorization or invent audio files. When narration exists, use actual returned duration and shift dependent timestamps; do not accelerate speech or omit facts to force sample timing. + +## Editability and acceptance + +- Keep `data-composition-variables` valid and statically parseable, with supported types and unique stable IDs matching the manifest. Preserve fixed-brand assets and editor hooks. +- Check short/long titles, dense content, contrast, image crops and safe margins with actual fonts/assets. Recompose or split within user constraints instead of shrinking all text or clipping required content. +- Inspect scene starts, readable middle frames, ends and transition overlaps, including direct backward and forward seeks and replay. A moving clock alone does not prove animation. +- Verify referenced local scripts load, the expected GSAP timeline is registered, media decodes and intended audio is audible in the real player. Timeline clips or waveforms alone do not prove sound. +- Run the session's HyperFrames/project and voiceover validation. Check the final scene, total bounds and no unintended blank/silent intervals; intentional pauses must have a content purpose. +- Verify theme changes preserve geometry/timing and editable controls still work. If export is requested, inspect the exported file's image, duration and audio separately. +- Report source checks, rendered frames, client playback, real-model generation and export as separate verification scopes. A static layout preview does not verify video playback or delivery. diff --git a/.codex/skills/ipollowork-template-generation/SKILL.md b/.codex/skills/ipollowork-template-generation/SKILL.md index 37e8c217d..0da3ab5a8 100644 --- a/.codex/skills/ipollowork-template-generation/SKILL.md +++ b/.codex/skills/ipollowork-template-generation/SKILL.md @@ -11,8 +11,8 @@ Create a reusable template, not a one-off artifact. The product-selected categor 1. Read [references/template-generation-contract.md](references/template-generation-contract.md). 2. Read exactly one surface reference: - - Design: [references/design.md](references/design.md) - - Slides or native editable PPT: [references/slides-ppt.md](references/slides-ppt.md) + - Design: [references/design.md](references/design.md), then its matching category reference (site, app, poster, cards, report, article or other) + - Slides or native editable PPT: [references/slides-ppt.md](references/slides-ppt.md), then [references/layout.md](references/layout.md) for reusable structure selection - HyperFrames Video: [references/video.md](references/video.md) 3. When converting an existing project, preserve its category, surface, structure, and source files. Saving creates a new personal template; it never updates the source template. diff --git a/.codex/skills/ipollowork-template-generation/references/design-app.md b/.codex/skills/ipollowork-template-generation/references/design-app.md new file mode 100644 index 000000000..69c8b7d19 --- /dev/null +++ b/.codex/skills/ipollowork-template-generation/references/design-app.md @@ -0,0 +1,22 @@ +# Application Interface Rules + +Use for `app`: screens, dashboards and interactive prototypes. Read `design.md` and shared guidelines first. + +## Tasks and structure + +- Identify the main user task, entry state, action and observable outcome. Select screens and states from that flow rather than copying a sample dashboard. +- Reuse navigation, controls, spacing and state language. Do not fill space with invented analytics, customers or activity. +- Choose suitable forms, tables, lists, inspectors and detail views. Marketing sections are not a substitute for a usable application flow. +- Keep the implementation boundary explicit: an HTML prototype may demonstrate local interaction, but does not establish authentication, persistence, payment or remote integration. + +## States and assets + +- Cover normal, loading, empty, invalid, failed and completed states needed by the flow. Keep transitions consistent; success must reflect an actual or clearly labeled simulated outcome. +- Preserve input after validation errors. Explain unavailable actions and protect destructive actions appropriately within the artifact's scope. +- Use labeled inputs, accessible state feedback, keyboard navigation and visible focus. Test menus, dialogs, escape/close and forms; do not rely on hover alone. +- Adapt dense navigation/data to narrow screens through intentional scrolling or alternate views, rather than clipping controls or squeezing labels. +- Follow shared media rules for meaningful product/content visuals. Prefer editable charts for data and consistent icons for navigation; decorative generation remains optional. + +## Acceptance + +Drive the primary flow from entry to outcome, including relevant empty/error/recovery cases. Check representative widths, long labels and realistic data volumes. Verify edit/save claims in the supported runtime. Distinguish prototype behavior from connected services and identify untested states. diff --git a/.codex/skills/ipollowork-template-generation/references/design-article.md b/.codex/skills/ipollowork-template-generation/references/design-article.md new file mode 100644 index 000000000..857d986a9 --- /dev/null +++ b/.codex/skills/ipollowork-template-generation/references/design-article.md @@ -0,0 +1,21 @@ +# Article Rules + +Use for `article`: editorial pages, long-form reading and WeChat articles. Read `design.md` and shared guidelines first. + +## Reading and editorial structure + +- Preserve facts, meaning and the requested voice. Derive title, introduction, sections, quotes and conclusion from content rather than a fixed template structure. +- Prioritize sustained reading: suitable line measure, paragraph rhythm and heading relationships. Check Chinese punctuation, mixed scripts and meaningful line breaks in the final font. +- Avoid turning every paragraph into a decorative card or slide. Use lists, emphasis and pull quotes to clarify; do not duplicate passages merely to fill slots. +- Keep captions, credits, links and sources associated with their passage/image. Never invent bylines, publication dates or attribution. + +## Assets and destination + +- Apply shared media rules to useful cover, setting, subject and supporting illustrations. Atmosphere is a valid purpose; there is no image quota. +- Preserve fixed brand header/footer images and nodes marked `data-ipw-fixed="true"`. Targeted text editing does not authorize changing locked elements. +- Distinguish browser articles from publishing-platform content. Use supported styles, links and interactions for the destination; browser preview does not establish WeChat paste/publishing fidelity. +- For actual email delivery, also read `design-other.md`'s email boundary. An article preview is not email-client verification. + +## Acceptance + +Read the full article in order and inspect its beginning, middle and ending at narrow and wide widths. Check loading/crops, captions, long links, spacing and CTA destinations. Verify requested transfer/export where available; otherwise retain the editable file and identify the unverified destination. Never claim publication without performing the authorized action. diff --git a/.codex/skills/ipollowork-template-generation/references/design-cards.md b/.codex/skills/ipollowork-template-generation/references/design-cards.md new file mode 100644 index 000000000..0fe0c286f --- /dev/null +++ b/.codex/skills/ipollowork-template-generation/references/design-cards.md @@ -0,0 +1,21 @@ +# Card Series Rules + +Use for `cards`: social carousels and shareable information card series. Read `design.md` and shared guidelines first. + +## Sequence and capacity + +- Content determines card count unless explicitly constrained. Give each card a clear role and maintain opening, progression and conclusion without forcing separate cards for each. +- Preserve requested channel dimensions and consistent series geometry. Do not convert cards into PPT or impose long-page scrolling on export canvases. +- Reuse typography, margins, attribution and numbering. Vary structure for different content relationships, not simply for decoration. +- Retain sufficient context when cards are shared alone. Keep values, units, sources and qualifications together; do not split claims from conditions to fit. +- Recompose or split dense content within user constraints rather than shrinking text. Keep content editable where supported. + +## Assets and behavior + +- Apply shared media rules across the series. Reuse a coherent visual family and check each crop; avoid redundant generation for repeated subjects. +- Do not bake final copy, figures or real logos into generated illustrations when separate editable objects are required. +- If interactive carousel behavior is requested, test next/previous, focus and touch. Static card exports do not need invented navigation or hover effects. + +## Acceptance + +Inspect every card and the series in order at final size and typical mobile reading scale. Check blank/duplicate cards, lost endings, numbering, safe areas and visual consistency. Verify requested export count, dimensions and order; report untested export behavior separately. diff --git a/.codex/skills/ipollowork-template-generation/references/design-other.md b/.codex/skills/ipollowork-template-generation/references/design-other.md new file mode 100644 index 000000000..92a5b8386 --- /dev/null +++ b/.codex/skills/ipollowork-template-generation/references/design-other.md @@ -0,0 +1,20 @@ +# Other Design Rules + +Use for `other` when no existing category fits the active artifact. Read `design.md` and shared guidelines first. Do not silently change an existing manifest to fit the routing table. + +## Establish the contract + +- Infer purpose, audience, canvas/viewport, editable content and format from the request/current files. Ask only about missing choices that materially change delivery. +- Record constraints briefly in the task. Do not invent a new category, runtime, app scaffold or specification file. +- Borrow relevant checks from the nearest type: site responsiveness, poster geometry, report evidence or article readability. Do not import unrelated navigation, pagination or exports. +- Apply shared layout/media rules. Without a dedicated catalog, reuse local patterns or create scoped structures with the existing theme. + +## Special delivery boundaries + +- Email: distinguish web mockups from actual email HTML. Establish target clients and a supported export/transfer path. Use compatible structure/styles, non-scripted actions and supported asset delivery. Check narrow layouts, image blocking, fallback text and links. Claim compatibility only for clients actually inspected. +- Image-led work: use media Skills for raster generation/editing; use Design for surrounding editable composition when needed. Raster references do not establish recoverable text layers or native vectors. +- Unusual print/interactive formats: inspect actual runtime/export capabilities before promising them. Continue independent work and identify concrete unsupported requirements. + +## Acceptance + +Verify the inferred contract using real content and the supported preview. Check completeness, readability, geometry, assets and relevant interactions; inspect requested exports when available. Identify which type checks were used and remaining limitations. HTML validity alone cannot establish acceptance of an unknown format. diff --git a/.codex/skills/ipollowork-template-generation/references/design-poster.md b/.codex/skills/ipollowork-template-generation/references/design-poster.md new file mode 100644 index 000000000..084b13b5c --- /dev/null +++ b/.codex/skills/ipollowork-template-generation/references/design-poster.md @@ -0,0 +1,20 @@ +# Poster and Banner Rules + +Use for `poster`: a single promotional canvas, poster or banner. Read `design.md` and shared guidelines first. + +## Canvas and hierarchy + +- Use requested dimensions, aspect ratio and viewing context. Preserve the existing canvas when unspecified; clarify only consequential missing dimensions. Do not inherit PPT's 16:9 requirement. +- Establish a focal message, supporting information and action. Preserve required dates, locations, terms, logos and contact details without treating sample copy as mandatory. +- Maintain safe margins and deliberate alignment. Fixed export canvases scale for preview without composition reflow. Responsive web banners may need a separate narrow composition; inspect each requested variant. +- Keep text/graphics editable where supported. Do not replace all content with a generated raster poster when editability is required. + +## Assets and output + +- Follow shared media rules for campaign, subject and atmosphere imagery. Preserve real product geometry and brand marks; never fabricate sponsors or endorsements. +- Judge resolution at final export size. Check crops, contrast, important subjects and text over images. Keep QR codes undistorted and test their destination when present. +- Apply print bleed, color-space and production requirements only when requested and supported. Browser HTML alone does not prove press-ready output. + +## Acceptance + +Inspect the entire canvas at final dimensions and intended reading scale. Check required copy, safe margins, overlap, sharpness and brand proportions. Inspect actual exports when requested; distinguish editable HTML from verified raster/print output. Static delivery needs no decorative animation. diff --git a/.codex/skills/ipollowork-template-generation/references/design-report.md b/.codex/skills/ipollowork-template-generation/references/design-report.md new file mode 100644 index 000000000..227657090 --- /dev/null +++ b/.codex/skills/ipollowork-template-generation/references/design-report.md @@ -0,0 +1,20 @@ +# Report Rules + +Use for `report`: research, business and data-led documents. Read `design.md` and shared guidelines first. + +## Evidence and reading structure + +- Organize around the question, findings, evidence, implications and limitations. Include methodology/source notes when needed; do not pad to a sample section count. +- Preserve facts, units, time ranges, denominators and qualifications. Separate measured data, estimates and assumptions. Missing evidence is a gap, not permission to invent data or citations. +- Use editable tables/charts for comparisons, trends and relationships. Label axes, units, legends and sources; avoid misleading visual encodings. +- Keep heading, summary, caption and note hierarchy consistent. Associate charts with explanations. Long reports may need working section links or a contents list. + +## Medium and assets + +- Distinguish responsive screen reports from paginated print/PDF. Preserve the active format; do not impose PPT geometry or promise pagination from HTML alone. +- Handle long tables intentionally: readable labels, headers and access to all columns. Inspect screen scrolling and actual page breaks for requested print output. +- Apply shared asset rules to useful contextual imagery. Generated images cannot replace research evidence, source charts or real case photography. + +## Acceptance + +Check source-to-output completeness, values and citations. Inspect all sections for clipping, repeated headings and unreadable density. Test screen navigation and narrow layouts. Inspect actual requested exports for blank pages, cropped tables and orphaned headings. Report factual uncertainty separately from layout quality and untested formats. diff --git a/.codex/skills/ipollowork-template-generation/references/design-site.md b/.codex/skills/ipollowork-template-generation/references/design-site.md new file mode 100644 index 000000000..80031c432 --- /dev/null +++ b/.codex/skills/ipollowork-template-generation/references/design-site.md @@ -0,0 +1,21 @@ +# Website Rules + +Use for `site`: websites, landing pages and portfolios. Read `design.md` and shared guidelines first. + +## Content and layout + +- Organize around audience, main promise, evidence and intended action. Sample feature, pricing and testimonial sections are optional patterns, not quotas. Never invent prices or endorsements. +- Reuse fitting source or supplied library sections; adapt or compose new sections in the current visual language. Do not reduce every relationship to a card grid. +- Use semantic landmarks and coherent headings. Align DOM and visual reading order; navigation labels must lead to real destinations. +- Use fluid layouts, readable measure, flexible media and content-driven breakpoints. Inspect narrow phone, intermediate and desktop widths, including the intended minimum width. Do not shrink a desktop canvas into unreadable mobile content. + +## Assets and interaction + +- Apply shared asset/model rules. Product and context imagery may help without being indispensable. Set intrinsic image dimensions, suitable alternative text and deliberate crops at each width. +- Keep primary content readable while media loads and when motion is reduced or enhancement fails. Animation must not block reading. +- Test menus, anchors, links, forms and primary actions with pointer and keyboard. Handle focus, validation and supported loading/error/success states. Never present local prototype feedback as a real service submission. +- Preserve the supported runtime; a static HTML task does not authorize a backend or app source changes. + +## Acceptance + +Inspect the full page, including below the fold, at representative widths. Check overflow, long localized titles, navigation collisions, crops, focus visibility and touch usability. Exercise real destinations and form behavior. Recheck after theme changes and asset insertion. Report disconnected integrations and untested viewports; a desktop screenshot alone is not responsive acceptance. diff --git a/.codex/skills/ipollowork-template-generation/references/design.md b/.codex/skills/ipollowork-template-generation/references/design.md index 64565bc93..abd5a1b54 100644 --- a/.codex/skills/ipollowork-template-generation/references/design.md +++ b/.codex/skills/ipollowork-template-generation/references/design.md @@ -1,11 +1,27 @@ -# Design Template Rules +# Design Type Routing -Use for Site, Landing, Poster, Social, Email, Report, and Image categories. +Read the [shared guidelines](template-generation-contract.md#ipollowork-shared-creative-and-layout-guidelines), then only the active type reference below. The session contract, manifest category, editable path and actual export capabilities are authoritative. Do not ask the user to choose an internal category when the task is clear. -- Use semantic HTML landmarks and accessible interactive controls. -- Keep responsive behavior intentional from narrow mobile widths through desktop. -- Keep all visual styling token-driven through `--ipw-*`; keep layout structure in template-owned CSS. -- Use local assets when possible and preserve intrinsic media geometry. -- Define a compact set of reusable content and visual variables that make sense for the selected category. -- Verify focus, hover, contrast, text overflow, empty content, and long localized copy. -- Theme switching may change style but must not rewrite DOM meaning or break responsive layout. +| Manifest category | Scope | Type reference or handoff | +| --- | --- | --- | +| `site` | Websites, landing pages and portfolios | [Website](design-site.md) | +| `app` | Application screens, dashboards and interactive prototypes | [Application](design-app.md) | +| `slides` | HTML presentations and native editable PPTX | Use `ipollowork-presentations`; repository template authors read `slides-ppt.md` and `layout.md` | +| `poster` | Posters, banners and single-canvas promotional designs | [Poster](design-poster.md) | +| `cards` | Social carousels and shareable information card series | [Cards](design-cards.md) | +| `report` | Reports, research summaries and data-led documents | [Report](design-report.md) | +| `article` | Editorial pages, long-form reading and WeChat articles | [Article](design-article.md) | +| `other` | Designs with no fitting existing category | [Other](design-other.md) | +| `video` | Timed compositions on the Video surface | Use `ipollowork-video-studio`; repository template authors read `video.md` | + +Landing, social, email and image are not additional manifest categories. Route landing pages to `site`, social card sequences to `cards`, and single promotional visuals to `poster`. Reading-oriented newsletters belong to `article`; actual email delivery also needs the compatibility checks in `design-other.md`. Generated image assets use media Skills. Preserve existing manifests; do not silently recategorize a user's project. + +For mixed artifacts, use the primary deliverable's rules and consult only relevant secondary sections. An embedded chart does not turn a website into a report; a dashboard screenshot does not make a poster interactive. + +## Shared execution boundary + +- Preserve project paths, semantic `--ipw-*` tokens, editor hooks and fixed brand regions. Initial generation adapts structure to content; targeted edits protect unrelated work. +- Apply shared asset rules to every type. A missing image slot or catalog does not remove a useful visual need. Type references add suitability checks, not competing model-selection or authorization policies. +- Read a layout library only when supplied by the session. Prefer fitting catalog or local patterns; extend when none fits. Do not invent catalog paths for categories without a library or require IDs for new structures. +- Inspect real content after fonts/assets load. Verify the requested output, not merely HTML source. Shared-style changes require checking every affected section/page. +- These references are guidance, not evidence of automatic enforcement or completed acceptance. Report source, rendering, interaction, editing and export checks separately. diff --git a/.codex/skills/ipollowork-template-generation/references/layout.md b/.codex/skills/ipollowork-template-generation/references/layout.md new file mode 100644 index 000000000..4d0efbbdb --- /dev/null +++ b/.codex/skills/ipollowork-template-generation/references/layout.md @@ -0,0 +1,139 @@ +# PPT Layout Guide · core-v1 + +This guide describes the ten reusable structures currently in the iPolloWork PPT library. It explains when to choose each structure, how to map content into it and when to adapt or replace it. The library is a preferred reuse source, not a mandatory whitelist or a complete inventory of template-local layouts. Use a better-fitting local pattern or write a new one when necessary, retaining the active visual and editable contracts. + +Start with `../core-v1-index.md` beside the session's category directory for shared relationships and type routing. This guide supplies PPT-specific fit and adaptation; shared creative/media policy remains in the shared guidelines. + +## Locate the source + +For a session that declares `layoutLibrary: "core-v1"`, the server materializes `core-v1-slides/` beside `brief.json`. This directory contains the quick index `catalog.md`, this `layout.md`, `shared-contract.md`, `shared.css` and the ten HTML files below. Resolve those files from the current session, not from the installed Skill's `references/` directory. A Skill-packaged copy of this guide is documentation, not a second copy of the HTML library. + +If the directory is absent in an older session, inspect available local patterns and the active contract. Do not invent file paths, assume missing layouts exist or overwrite the user's project merely to obtain a library. Read only the relevant candidate HTML and styles. + +Repository ownership: this document is maintained in `.codex/skills/ipollowork-template-generation/references/layout.md`. The server bundle and both presentation Skill distributions carry checked copies. Source HTML/CSS lives under `apps/server/bundled-templates/core-v1-slides-*`; the server assembles those flat resources into the session directory above. + +## Selection map + +| Layout file | Content relationship | Main slots | Trial capacity | +| --- | --- | --- | --- | +| `comparison.html` | Two alternatives on shared criteria | Title, option names, criteria, paired evidence, takeaway | 2–3 criteria | +| `statement-visual.html` | One main statement supported by a visual | Eyebrow, title, paragraph, visual | One message and one visual | +| `parallel-principles.html` | Peer principles or capabilities | Title, numbered labels, headings, paragraphs | 2–3 peer items | +| `lead-support.html` | A lead case with supporting observations | Title, case label/heading/body, supporting headings/bodies | One case and 1–2 observations | +| `step-sequence.html` | Ordered actions or learning stages | Title, numbers, step headings/bodies | 3–5 steps | +| `milestone-staircase.html` | Successive milestones earned through evidence | Title, stage/date labels, outcomes, evidence, note | 3–4 stages | +| `editorial-visual.html` | Image-led narrative or setting | Eyebrow, title, paragraph, main visual, caption/source | One image and short explanation | +| `quote-wall.html` | Related but distinct attributed voices | Title, segment, main quote/attribution, supporting quotes/attributions | One lead and 1–2 short quotes | +| `evidence-matrix.html` | Findings across comparable groups or options | Title, column/row labels, findings, details, source | Up to 3 rows × 3 comparison columns | +| `metric-scorecard.html` | One key result with supporting measures | Title, primary label/value/context, supporting labels/values, source | One primary and 2–4 secondary metrics | + +These counts describe trial structures, not quotas or validated limits for every language/theme. Source grids demonstrate particular counts; removing an item also requires adjusting columns, rows and proportions. Content and explicit user constraints determine page count. + +## Reuse procedure + +1. Identify the message, evidence and content relationship. Assess asset purpose, existing files and gaps, and make required capability queries under the shared guidelines before committing to text or geometry. +2. Compare the template's local patterns and relevant entries below. Open candidate source HTML, read `data-layout-description` and `data-slot`, and inspect the actual DOM and `shared.css` dependencies. +3. Read `shared-contract.md`. Copy the selected `
` and the relevant scoped CSS, including shared baseline selectors covering that layout. Omit `html`, `body`, `main`, preview `:root` values and demo scripts. Bind to the active theme's semantic `--ipw-*` tokens. +4. Replace every example and assign valid unique slide/object identifiers and ordering. Retain `data-ipw-slide` and the matching editable-object markers. Optional slots may be removed; update layout geometry accordingly. +5. Generate/reuse and place required assets, then trial real short/dense content and long titles with final fonts. Adjust locally or split within user constraints. Never use all-page font shrinking, hidden overflow or responsive reflow as a fixed-canvas workaround. +6. Check actual rendering, relevant client editing and requested exports separately. Do not claim one-off extensions or untested exports are verified library capabilities. + +The structural library and asset Skills have separate responsibilities. Example shapes do not prohibit imagery. Native editable PPT supports marked image objects; a Markdown source or editability requirement does not justify skipping a required media query. Follow shared model-selection and authorization rules rather than adding another approval flow here. + +## 1. Comparison + +- **Source:** `comparison.html`, `.ipw-layout-comparison`; adapted from Brand Narrative's `.tension` relationship. +- **Use for:** two alternatives evaluated on the same dimensions, with a conditional recommendation. +- **Slots:** `title`, `option-a`, `option-b`, `criterion-1…3`, paired `a-1…3`/`b-1…3`, `takeaway`. +- **Capacity:** trial 2–3 short criteria, concise paired evidence and one takeaway. Keep units and uncertainty comparable across both sides. +- **Variants:** remove an unused row, widen the criterion column, adjust the evidence-column ratio or split dense dimensions across pages. Keep corresponding rows aligned. +- **Avoid:** unrelated items presented as a comparison, invented metrics or long narratives crammed into cells. More than two alternatives may need a table or a new structure. + +## 2. Statement and visual + +- **Source:** `statement-visual.html`, `.ipw-layout-statement-visual`; adapted from Brand Narrative's `.manifesto`. +- **Use for:** an opening, chapter or conclusion centered on one statement. +- **Slots:** `eyebrow`, `title`, `body`, `visual`. +- **Capacity:** start with a 2–3-line title and a 3–5-line supporting paragraph, then measure with the target font and width. +- **Variants:** adjust the column ratio, widen or vertically reorganize the title region, and replace the sample circle with a meaningful image, editable chart or graphic. Keep one dominant focus. +- **Assets:** the circle only demonstrates space. If replacing it with an image, remove `data-pptx-shape`, add `data-pptx-image`, provide actual `src`/`alt`, and revise shape-specific sizing/crop rules. +- **Avoid:** preserving the circle merely because it is in the sample, or letting a long title cover the supporting text. + +## 3. Parallel principles + +- **Source:** `parallel-principles.html`, `.ipw-layout-parallel-principles`; adapted from Brand Narrative's `.voice-spectrum`. +- **Use for:** genuinely peer principles, capabilities or summary points. +- **Slots:** `title`, `label-1…3`, `heading-1…3`, `body-1…3`. +- **Capacity:** 2–3 items, each with a short heading and brief explanation. The source uses three columns; a two-item variant must use two columns rather than leave an empty third. +- **Variants:** reduce columns, balance width against actual copy, remove unnecessary labels or split longer explanations. +- **Avoid:** flattening a hierarchy or sequence into peer cards, or reducing all typography to preserve three columns. + +## 4. Lead and support + +- **Source:** `lead-support.html`, `.ipw-layout-lead-support`; adapted from Brand Narrative's `.expression`. +- **Use for:** one main case/outcome explained by evidence and conditions. +- **Slots:** `title`, `case-label`, `case-heading`, `case-body`, `support-heading-1…2`, `support-body-1…2`. +- **Capacity:** one focused case and 1–2 supporting observations. Keep background, action and result concise and sourced. +- **Variants:** change primary/secondary proportions, remove an unused support block or move excess evidence to another page. The lead region may be adapted to actual imagery plus a readable caption. +- **Avoid:** presenting a single case as universal proof or leaving unused blocks filled with generic text. + +## 5. Step sequence + +- **Source:** `step-sequence.html`, `.ipw-layout-step-sequence`; adapted from `ipollowork.pptx-learning-journey/entry.html`, slide 5, `.chapters`. +- **Use for:** ordered actions, a learning path or a repeatable process. +- **Slots:** `title`, `number-1…5`, `heading-1…5`, `body-1…5`. +- **Capacity:** 3–5 steps, each with a short heading and one explanatory sentence. The five-column example requires especially concise copy. +- **Variants:** reduce the grid to the actual step count, group related steps into phases or move detailed instructions to subsequent pages. Preserve an unambiguous reading order. +- **Avoid:** unordered peer principles, branching workflows disguised as a single line, or long procedural text in narrow columns. + +## 6. Milestone staircase + +- **Source:** `milestone-staircase.html`, `.ipw-layout-milestone-staircase`; adapted from `ipollowork.pptx-venture-blueprint/entry.html`, slide 6, `.staircase`. +- **Use for:** stages where an achieved outcome enables the next stage. +- **Slots:** `title`, `date-1…4`, `heading-1…4`, `evidence-1…4`, `note`. +- **Capacity:** 3–4 stages with a date/phase label, short outcome and evidence line. The first step has the least vertical capacity; check it first. +- **Variants:** adjust actual column count and step heights, shorten nonessential wording or split the roadmap. Heights indicate sequence only, never quantitative magnitude; use a chart for measured values. +- **Avoid:** invented deadlines or progress metrics, lengthy evidence inside the shortest step, and treating decorative height as data. + +## 7. Editorial visual + +- **Source:** `editorial-visual.html`, `.ipw-layout-editorial-visual`; adapted from `ipollowork.pptx-film-treatment/entry.html`, slide 1, `.cover` and `.hero-art`. +- **Use for:** image-led narrative, a setting, an observed subject or a cover where visual context matters. +- **Slots:** `eyebrow`, `title`, `body`, `visual`, `caption`; `visual-placeholder` exists only inside the replaceable demo slot. +- **Capacity:** one main visual, a short title/paragraph and a caption/source. Trial a two-line title; rebalance text width or height for longer titles rather than forcing that count. +- **Variants:** adjust image/text proportions, crop to retain the subject, use contain-fit when cropping would discard evidence, or split the explanation from the image. +- **Assets:** replace the entire placeholder with `Meaningful description`, using a real saved file. Remove the placeholder text and shape marker; supply an accurate caption/source. Editable diagrams may use a purpose-built structure instead. +- **Avoid:** shipping the placeholder, using decorative geometry to bypass required asset discovery, or presenting generated illustration as documentary evidence. + +## 8. Quote wall + +- **Source:** `quote-wall.html`, `.ipw-layout-quote-wall`; adapted from `ipollowork.pptx-research-signals/entry.html`, slide 4, `.quote-wall`. +- **Use for:** related but distinct voices that support or qualify a main observation. +- **Slots:** `title`, `segment`, `quote`, `attribution`, `quote-1…2`, `attribution-1…2`. +- **Capacity:** one main quote of roughly 2–4 rendered lines and 1–2 brief supporting quotes, each with an attribution. Sample quote text is illustrative and must be replaced or removed. +- **Variants:** remove an unused side quote and update grid rows, widen the main quote area, or dedicate a page to a long essential quotation. +- **Avoid:** invented testimonials, unattributed quotes, editing a quotation in ways that change its meaning, or presenting one participant as an entire group's view. + +## 9. Evidence matrix + +- **Source:** `evidence-matrix.html`, `.ipw-layout-evidence-matrix`; adapted from `ipollowork.pptx-research-signals/entry.html`, slide 5, `.matrix`. +- **Use for:** comparable findings across groups, options or contexts with explicit uncertainty. +- **Slots:** `title`, `column-0…3` (including the row-label header), `row-1…3`, `finding-r-c`, `detail-r-c`, `source`. +- **Capacity:** up to three observation rows and three comparison columns plus the row-label column. Each cell holds a short finding and qualifier, not a paragraph. +- **Variants:** reduce actual rows/columns and update the grid, widen row labels, or split by evidence dimension. Keep source, sample definition and limitations visible. +- **Avoid:** invented confidence scores, incomparable data definitions, unsupported rankings, or compressing a large research table into unreadable cells. + +## 10. Metric scorecard + +- **Source:** `metric-scorecard.html`, `.ipw-layout-metric-scorecard`; adapted from `ipollowork.pptx-annual-review/entry.html`, slide 2, `.scorecard`. +- **Use for:** a primary outcome interpreted through a small set of supporting measures. +- **Slots:** `title`, `metric-label`, `metric-value`, `metric-context`, `label-1…4`, `value-1…4`, `source`. +- **Capacity:** one primary metric and 2–4 supporting metrics. The source uses a 2×2 secondary grid; adjust rows/columns when using fewer values. +- **Variants:** reallocate the primary/secondary ratio, use consistent number formatting or split distinct metric families. Include actual units, period, definitions and sources; sample numbers are not user data. +- **Avoid:** incompatible time ranges, unsupported growth claims, value labels separated from units, or oversized numbers that collide after a font change. + +## Verification scope + +The current ten source previews have browser-rendering coverage at 1280×720. The six added patterns also have a longer Chinese title/theme-change check, with image-node replacement exercised for `editorial-visual`. These checks do not establish all-language capacity, real-model selection behavior, complete client editing or native PPTX export fidelity. Verify those separately for the actual task. + +Review all selected pages with real content and final assets, and distinguish source, visual, client and export checks in the task record. Missing global entries remain valid local reuse candidates. New structures are permitted; only promote them into this library after separate validation and an intentional library update. diff --git a/.codex/skills/ipollowork-template-generation/references/slides-ppt.md b/.codex/skills/ipollowork-template-generation/references/slides-ppt.md index 314653a8e..8cb863fda 100644 --- a/.codex/skills/ipollowork-template-generation/references/slides-ppt.md +++ b/.codex/skills/ipollowork-template-generation/references/slides-ppt.md @@ -1,19 +1,134 @@ -# Slides And Native PPT Rules +# Slides and Native PPT Rules -Use for Presentation and native editable PPT. The application-selected PPT mode is authoritative. +Applies to iPolloWork presentations and native editable PPT. Read the [shared guidelines](template-generation-contract.md#ipollowork-shared-creative-and-layout-guidelines) first. This reference adds PPT authoring and acceptance requirements; the selected mode, injected session contract and actual export capabilities remain implementation boundaries. For the ten reusable core-v1 structures, read the [layout guide](layout.md), then open only relevant source layouts. -## Shared Slides +Status: authoring guidance, not proof of automatic injection into every engine or automated enforcement of every check. Do not claim experience or export verification without performing the relevant rendering and export checks. -- Use a fixed 16:9 stage and recognized `data-ipw-slide` roots. -- Keep slide roots, order, count, and object geometry stable unless the user explicitly changes the story. -- Tokenize text, fills, borders, shadows, and decorative styling without moving objects. -- Keep copy concise enough to fit the fixed stage and verify long text does not overflow. +## 1. Determine task scope -## Native Editable PPT +| Task | Allowed changes | Preserve | +| --- | --- | --- | +| Initial generation | Determine count/order from content; reuse, repeat, combine, remove or extend template patterns | Explicit constraints, visual identity, fixed canvas, runtime and editable contracts | +| Narrative rewrite or full redesign | Reorder, add/remove or rebuild pages within the request | Valid facts, assets, user edits and style not authorized to change | +| Targeted edit | Edit specified pages/objects and adjust layout within those pages when necessary | Unrelated pages, content, order and objects; shared CSS must not affect them | +| Theme-only change | Update semantic tokens and check real rendering | Page count/order, content, assets, canvas, object positions and editable markers | -- Preserve `data-pptx-text`, `data-pptx-shape`, and `data-pptx-image` markers on every object that must remain editable after export. -- Keep marked objects structurally simple and their bounds deterministic. -- Do not flatten editable text or shapes into screenshots. -- Validate both the slide document and editable marker coverage before saving. +Initial generation does not inherit the template's sample count, narrative or brand data. If a theme change causes font overflow, first check font mappings and typography parameters. Explain any remaining conflict requiring object rearrangement rather than silently moving objects. Resolve exact-layout versus complete-content conflicts under the shared guidelines. -Theme switching must never alter stage dimensions, slide roots, PPT object markers, or export eligibility. +## 2. Read the brief and plan the narrative + +- Read the current entry, confirmed requirements, existing pages, tokens, template guide and applicable layout index. Load only relevant candidates. +- Identify audience, purpose, language, setting, main conclusion, evidence and delivery format from existing materials. Proceed when sufficient; ask only about consequential gaps. +- Content and explicit user constraints determine page count. Speaking time can inform pacing, not a fixed minutes-per-slide quota. Examples and capacity hints are not hard page-count requirements. +- Plan each page's message, content relationship, evidence and asset purpose. Check reusable assets and gaps, query capabilities under the shared rules, then select or create a layout. This plan guides execution; do not require approval of internal IDs or an outline unless the user requests it. +- Give each slide one main reading task. Prefer headings that state a conclusion or question, supported by evidence. Use section pages when useful, not mandatory agenda, transition or thank-you pages merely to fill a formula. +- Separate facts, assumptions and missing information. Replace/remove example figures, logos and testimonials rather than presenting them as real user outcomes. + +## 3. Select and extend layouts + +Select structure by content relationship, then map it to the active visual language. The following are selection criteria, not a claim that every pattern is installed. + +| Relationship | Consider | Check | +| --- | --- | --- | +| Statement, opening or chapter | A strong heading with one meaningful visual | Clear emphasis without decorative filler | +| Comparing options | Aligned columns or a comparison table | Common dimensions; adjust proportions for uneven content | +| Steps, development or stages | Process, timeline or phase structure | Clear order and connections, not unordered cards | +| Data or evidence | Key metrics, charts, tables and sources | Units, definitions, period, axes and conclusion agree | +| Case study or audience | Lead case with evidence, or suitable profile structure | A concrete subject, not generic copy with renamed people | +| Principles, capabilities or summary | Peer items or a hierarchy | Genuine peer relationships; do not flatten a hierarchy | + +- Prefer suitable local or shared patterns. Read their real source and CSS dependencies rather than guessing from filenames. +- Copy only selected structural fragments and local styles, bound to current theme tokens. Omit preview hosts, scripts, default palettes and fonts. +- Replace content before adjusting columns, proportions, image/text areas and optional slots. If none fits, extend with the active typography, graphic and spacing language; do not replace the theme. +- Repeating a pattern is useful for comparable cases or data. Avoid mechanical repetition without a content reason, but do not force adjacent pages to differ. +- Maintain valid unique page/object identifiers and order, retaining recognized `data-ipw-slide` roots. +- Shared catalog, local source and new layouts are all valid sources. A local pattern absent from the global catalog is not a violation. Give new structures meaningful `data-layout` IDs and describe their relationship, slots and capacity in the page plan. Global registration or `data-layout-origin="extension"` is not a prerequisite. Do not automatically add a one-off layout to the global library or call it verified. +- Fixed-canvas extensions must not use viewport reflow or off-canvas clipping to conceal overflow. Adjust structure, remove empty slots or split pages. A negative local offset alone is not failure; inspect actual text/shape bounds and editable export behavior. + +## 4. Capacity and Chinese typography + +- Retain the supported fixed 16:9 canvas; do not add mobile stacking or breakpoint reflow. Check product support before adopting another requested ratio. +- Use coherent roles for headings, body, notes and sources. Choose sizes, leading and whitespace for the template and viewing scale, not chat typography or a generic website scale. +- For dense content, tighten nonessential wording, adjust space or choose another structure; split if page constraints permit. Do not shrink all text, compress leading, clip content or omit essential facts to force a fit. +- Inspect long Chinese titles for semantic breaks, glyph collisions, orphans and distance from body text. `text-wrap: balance` is only an aid. Check font fallback, values/units and long Latin words in mixed text. +- Charts must be readable at presentation scale, with visible sources and necessary notes. Do not encode important distinctions with color alone. +- Review reading order among title, body, image and source, and consistency of margins/density across pages. No overflow does not imply good layout. + +### Capacity planning and overflow handling + +For each selected pattern, identify the content relationship, real source, title/body areas, available line capacity with the current font, image ratio, allowed variants and overflow response. Use an existing catalog entry when available; otherwise measure the source and record findings in the current page plan. Do not invent verified limits or create a separate library for one generation task. + +Capacity depends on actual font, size, leading and space, not a universal Chinese-character count. Trial the longest title and densest page first. If a narrow-column title exceeds its planned lines, reallocate space or change structure; do not leave body text at a fixed start that collides with it. With no existing typography specification, a 1280×720 trial baseline is 40–56px headings, 24–30px body and supporting text at least 18px; scale proportionally for other canvases. These are starting points requiring visual review, not overrides of user/template standards or permission to shrink long copy. + +Existing Brand Narrative patterns provide these planning starting points, not multilingual hard limits: + +| Source | Suitable content and slots | Capacity response | +| --- | --- | --- | +| `.manifesto` | One statement, support paragraph and visual | Trial 2–3 title lines; widen or stack regions before support text collides | +| `.tension` | Two sides compared on common dimensions | Short heading/evidence per side; adjust proportions, use a table or split for multiple dimensions | +| `.audience-collage` | A few audience/person keywords and explanations | Scattered keywords cannot hold long narratives; use ordered image/text regions for longer descriptions | +| `.positioning` | Two justified dimensions and positions | Short readable axis labels with separate explanation; do not force literary narrative into a positioning map | +| `.voice-spectrum` | Peer principles and brief explanations | Check each real column width; reduce columns or split rather than shrinking all text | +| `.expression` | Lead case and supporting content | Clear primary/secondary slots; review real image crops; move excess evidence to another page | + +Custom work uses the same capacity rules. Establish a coherent visual language before selecting structures; extend when none fits. Custom does not mean designing every page arbitrarily from scratch, and shared preview colors/fonts do not replace the chosen theme. + +### Contrast and line-break review + +- Check actual backgrounds behind text, including photos, gradients, color edges and overlays. Target at least 4.5:1 for normal text and 3:1 for large text. Large means at least 24px regular or about 19px bold at actual display scale, not a magnified screenshot. Check the least favorable image region; move text or add a theme-consistent stable backing when needed. Comparing token values alone is insufficient. +- Break Chinese headings semantically and avoid body endings with only 1–2 characters or punctuation. Adjust text width, remove unsuitable hard breaks or change layout before tightening wording without losing meaning/facts. Preserve verbatim copy when requested. Do not shrink the whole slide to eliminate orphans. +- Title, body and notes need distinct regions that fit their real content. Inspect rendered line boxes and following regions; overflowing fixed-height titles must not cover body text. Deliberate layering is acceptable, unreadable text is not. + +## 5. Theme and assets + +Native editable PPT can contain `data-pptx-image` objects. Editability covers supported properties such as position and size; every image pixel need not become a vector object. Do not omit appropriate imagery to guarantee editability. If multiple suitable models require a choice, ask once before committing any image-dependent page; continue independent layout work only with the asset marked pending, and never silently use `defaultModel` or downgrade to shapes merely to avoid the question. + +- Retain a selected template's visual identity unless restyling is explicitly requested; a changed audience alone is not authorization. +- Use current semantic tokens and preserve the `design-tokens.css` contract. Do not restore sample colors, add inline theme overrides or import another global theme. +- Follow the shared asset-selection, authorization, model-choice, cost and failure rules. Do not require a model selection for every routine generation call. +- Apply the shared visual-purpose decisions during page planning; no separate per-slide assessment report is required. Proactively supplement imagery that improves understanding or atmosphere, reuse adequate assets, and keep data/process/architecture diagrams editable. Pure decoration does not require generation. No fixed image quota applies; generated illustrations cannot replace real evidence. +- Visual slots can contain images, editable charts or shapes. Sample geometry is not a fixed asset requirement. Use `data-pptx-image` when replacing a slot with an image and adjust its container/crop. Missing image slots or editable-output goals do not cancel a legitimate asset need. +- Check resolution, crop, proportion and image/text relationships. HTML playback does not establish media support in the requested PPT format; verify actual export support before embedding. +- Save files/assets in the current `design//` and reuse existing asset directories; do not create a parallel project. + +## 6. Editing, playback, notes and motion by mode + +### Native Editable PPT + +- Preserve supported `data-pptx-text`, `data-pptx-shape` and `data-pptx-image` markers on objects that need editable export, following the injected visible-object coverage contract. +- Give each element one PPTX object type. A text card uses a shape container and separate marked text children, not shape/text markers on the same node. Check exported text per page; object counts alone do not prove completeness. +- Use explicit supported shape nodes for meaningful decoration, not unmarked pseudo-elements. Browser visibility does not prove PPTX inclusion. +- Keep object geometry simple and measurable. Do not assume lossless export of complex DOM/CSS, or flatten editable text/shapes/pages into screenshots. +- The Design panel owns navigation. Do not add scripts, keyboard handlers, page controls, navigation buttons or speaker-note nodes, and do not transplant OpenDesign's runtime. +- Do not add animation frameworks or promise PPTX animation retention by default. Verify support for requested effects, explaining unsupported cases and feasible alternatives. +- Use actual supported notes functionality. If notes cannot be embedded, provide a separate script when requested and state that it is not inside the PPTX. + +### HTML Presentation + +- Retain the template's supported fixed canvas, keyboard navigation, controls and notes contract; do not add a second runtime. +- Add speaker notes only when supported and needed. Keep presenter guidance separate from audience-visible content. +- Use existing motion to explain sequence/emphasis, usually with one clear focus per page; do not animate everything mechanically. Verify navigation, replay and screenshots do not leave content invisible. +- Working HTML playback is not verified editable PPTX export. Identify the actual delivered format. + +## 7. Generation and acceptance loop + +Follow read → asset assessment and required capability queries → page planning and layout selection/extension → asset generation, saving and placement → inspect/repair → deliver. + +1. **Content:** compare the page plan with user materials; verify narrative, facts, units, sources and essential conditions. Replace sample content and list required gaps. +2. **Structure:** use existing validators for fixed canvas, slide roots, identifiers, resource references and marker coverage. Template-package acceptance follows the shared contract separately and does not replace artifact-experience checks. Distinguish shared reuse, local reuse and extensions instead of enforcing a global ID whitelist. Positioning/overflow checks identify candidates; actual clipping, obstruction, canvas violations or lost editability justify repairs. + **Assets:** verify decisions, actual required queries, generated/reused results and actual references. Replacing absent source photos with geometry without required queries leaves the media workflow incomplete. Prefer editable data/process diagrams; do not accept or reject by image count. +3. **Deck overview:** inspect all thumbnails for visual consistency, density and narrative rhythm. Repeated patterns need a content reason. +4. **Every-slide rendering:** wait for fonts/assets and inspect every page at target size, not just the cover or a sample. Focus on long Chinese titles, dense pages, charts and new layouts for overlap, overflow, orphans, crop and contrast. Preview-only page switching must not alter the output runtime contract. Standalone HTML captures do not replace client navigation checks. +5. **Client experience:** actually navigate the appropriate editor and exercise affected capabilities. For native PPT, verify representative text, shape and image edits; for HTML, verify navigation and affected notes/motion. +6. **Requested export:** use the supported product path and inspect actual PPTX/PDF/image files when requested. PPTX needs both visual and editability checks; markers, filenames or HTML captures alone prove neither. Export entry points must be discoverable and callable. If no model-callable client export exists, preserve editable source and direct the user accurately to client export. Do not blindly scan/install tools or reconstruct approximate layouts as a substitute for native export. Use standalone PPTX generation only when explicitly requested and verify it separately. +7. **Repair and recheck:** follow the shared executable repair loop. Locate issues per page, repair locally and capture again using the latest files. Fix obscured/unreadable content before orphans, spacing and rhythm. Recheck every page affected by shared-style changes; do not repeatedly regenerate the whole deck without cause. + +If client, rendering or export access is missing, preserve artifacts and distinguish checked, unverified and unfinished work. Source checks are not real-experience verification. Essential missing content, broken resources, obstruction or lost required editability are must-fix issues under the shared rules. + +Deliver the current entry, actual completed exports and a short explanation. Never list unperformed exports as results. Nontechnical users do not need internal layout IDs, object markers or complete validation logs. + +## References and maintenance + +OpenDesign's [PPT authoring workflow](https://github.com/nexu-io/open-design/blob/main/design-templates/html-ppt/references/authoring-guide.md) and [PPT Skill](https://github.com/nexu-io/open-design/blob/main/design-templates/html-ppt/SKILL.md) informed requirements gathering, theme/layout separation, page-level authoring and browser review. These rules are rewritten for iPolloWork's native editing, theme and export constraints; they do not copy template code or runtime. + +Maintain cross-type principles in the shared contract and PPT-specific rules here. The [layout guide](layout.md) describes reusable core-v1 structures; template-local patterns belong in `authoring.md`. OpenDesign's mandatory adjacent-layout changes, fixed speaking/page-count suggestions, presentation runtime and decorative animation requirements are not iPolloWork defaults. Automatic injection and real-model execution require separate verification; updated documents alone do not prove every engine follows them. diff --git a/.codex/skills/ipollowork-template-generation/references/template-generation-contract.md b/.codex/skills/ipollowork-template-generation/references/template-generation-contract.md index 661efcbb3..d1582cc47 100644 --- a/.codex/skills/ipollowork-template-generation/references/template-generation-contract.md +++ b/.codex/skills/ipollowork-template-generation/references/template-generation-contract.md @@ -2,6 +2,206 @@ The service implementation in `apps/server/src/templates.ts` and shared schemas in `packages/types/src/templates.ts` are the hard truth. This reference explains the creative workflow; it does not replace validation. +## iPolloWork Shared Creative and Layout Guidelines + +Status: authoring guidance for template application, content generation and subsequent editing, not the client's UI style specification. These requirements do not imply that every engine receives them automatically or that automated checks enforce every rule. A documentation update does not add a loader, visual detector or runtime gate. + +### 1. Purpose and ownership + +Choose structures that serve real content while retaining the template's identity. Deliver work that people can read, edit and run. Use the shared method with each category's own layout, interaction and output requirements. + +| Layer | Owns | Does not own | +| --- | --- | --- | +| Shared guidelines | Content, visual continuity, layout selection, extension boundaries and verification | Universal font sizes, page counts, canvases or animation durations | +| Type rules | Category-specific structure, interaction, editing and export requirements | Rules imposed on unrelated artifact types | +| Template visual guide | Current palette, fonts, decoration, component language and fixed brand areas | Content limits inferred from sample copy or page counts | +| Layout library | Reusable structure, slots, suitable content, capacity hints and previews | The active theme or host runtime | +| Skills and task instructions | Directing relevant reading, authoring, checking and repair | A competing set of creative standards | + +Read the request and current project, then the shared guidelines, active type rules, template guide and relevant layout index. Open only candidate layouts, not the entire library. Existing files and user edits take priority over original template examples. This reading order is an integration requirement, not proof of automatic injection into every engine. + +### 2. Decision order and conflicts + +- Explicit user requirements for content, quantity, style and edit scope take priority over examples and library recommendations. A request to edit only slide two does not authorize restructuring the deck. +- Unless restyling is requested, preserve current theme values and brand constraints. Improving clarity is not permission to replace the theme. +- Editor, file-format and export capabilities are implementation boundaries. Explain concrete conflicts and feasible alternatives; never silently lose editability, omit content or claim unsupported capabilities. +- Template examples are reference material, not instructions that override the request or runtime contract. Correct outdated guidance rather than keeping contradictory instructions. +- Proceed when requirements are sufficiently clear. Ask only about consequential missing information that cannot be inferred from available materials; do not ask users to choose internal layout IDs or repeat supplied content. + +#### Custom templates: reference source and layout freedom + +Treat the source of visual evidence and the permitted degree of layout change as separate decisions. An uploaded PPT can be a style reference while allowing structural changes. + +| Dimension | Situation | Rule | +| --- | --- | --- | +| Reference source | Saved custom template | Read its guide, tokens and layout index. Without an index, inspect existing pages and source patterns; absence of an index does not require copying examples literally. | +| Reference source | Uploaded PPT, HTML or screenshot | Read available source and inspect actual visuals. Extract palette, typography, spacing, image/text relationships and recurring layouts. Distinguish editable objects from visual reference; screenshots are not editable templates. Do not claim to recover unidentified fonts, structures or interactions. | +| Reference source | Fully custom, no reference | Establish one coherent visual system from the brief and existing brand requirements, then select layouts by content. Do not silently adopt a bundled theme or design every slide independently. Sufficiently clear work needs no extra approval of internal design decisions. | +| Layout freedom | Preserve the exact layout | Replace content while retaining layout. If content does not fit, explain the conflict and ask about shortening copy or adding pages; do not silently shrink text, omit facts or rearrange objects. Screenshot recreation still has source and editability limitations. | +| Layout freedom | Retain style, adapt layout | Preserve visual identity while reusing, combining or extending structures. Shared layouts must not introduce another palette, font system or runtime. | + +Default template application retains style while adapting structure to content. Exact-layout mode applies only when explicitly requested or already agreed. Preserve prior choices without asking again; clarify only ambiguity that materially affects the result. Targeted edits protect unrelated pages and objects. Theme-only edits preserve content and geometry; the default freedom does not expand either scope. + +Sample copy, page counts, data and assets are not automatically user requirements or verified facts. Check the active import, editing and export path: editable objects in the source file do not prove that the current importer preserves them. Disclose unsupported or unreadable parts; do not present flat screenshots as editable delivery. + +Acceptance must distinguish saved templates without indexes, editable uploads, screenshot-only references and custom work without references, as well as exact-layout versus adaptive modes. Claim verification only for combinations actually exercised; bundled-template tests do not prove all custom-template cases. + +### 3. Content before structure + +Identify audience, purpose, main message, supporting material and intended action before organizing pages, sections or scenes. + +- Content determines page count, scene count and duration. Examples are not quotas. Only explicit user quantities constrain the result; distinguish approximate targets from strict limits. +- Separate facts, goals, assumptions and unresolved information. Never invent data, sources, testimonials, customer logos, prices or outcomes to fill a layout. +- Preserve important facts, conditions, units and source relationships. Tighten wording without removing qualifications or evidence merely to fit. +- An empty slot may mean the structure is unsuitable. Remove unnecessary slots or change layout instead of padding with meaningless copy. +- Produce actual files when information is sufficient. If confirmation is necessary, pause only dependent work. A confirmed video script does not need the same approval again. + +### 4. Preserve visual identity + +- Retain the current palette, typography, radii, decoration and overall character by default. A new topic or audience does not authorize a brand redesign. +- Use current semantic `--ipw-*` tokens. Keep structural CSS separate from theme values; do not create another theme in inline styles or scripts. Follow the Design-System Layer contract below where applicable. +- Shared layouts supply structure and capacity guidance. Map them to the active visual language; omit preview palettes, fonts, hosts and demo scripts. +- Preserve proportions of logos, icons and photos. Keep fixed brand areas; update editable brand slots from user content. Demo logos are not customer endorsements. +- Do not categorically reject particular colors, serif fonts, gradients or symmetry. Judge readability, template intent and user requirements rather than imposing a universal aesthetic. +- Theme changes must not rewrite content, replace images or reorder pages. Check actual typography after font changes to catch new overflow. + +### 5. Select and extend layouts + +Identify the content relationship: statement, comparison, process, data, case study, hierarchy or summary. Compare local and shared patterns and prefer a suitable structure that retains the style; neither source has unconditional priority. + +The catalog is a preferred reuse source, not an ID whitelist or a complete inventory of extracted templates. Local source patterns remain valid even when absent from the global catalog. When none fits, write a new layout within the current visual language and record its origin, relationship, slots and capacity in the page plan. A new ID, missing global registration or missing provenance attribute is not grounds for rejection. Validate content fit, rendered layout and type contracts. Do not label a one-off extension as a verified library pattern; admission requires separate real-content, client-preview and applicable export checks. + +| Situation | Action | +| --- | --- | +| Relationship and capacity fit | Reuse, replace content and check actual rendering | +| Relationship fits; capacity differs slightly | Adjust columns, proportions, alignment, image/text area or optional slots | +| Relationship does not fit | Select another pattern; do not force a sequence into unordered cards | +| No suitable existing structure | Extend with the current template's visual elements and retain the type runtime contract | +| Exact layout is required but content will not fit | Explain the conflict and offer copy reduction or additional pages/scenes; do not omit content without permission | + +Extension is not a theme change. Scope new CSS locally so one edit does not affect unrelated pages. Repeat structures when comparison benefits from consistency; do not force variety or turn everything into the same card simply for convenience. + +Capacity is a selection hint, not a hard limit on user content. First tighten nonessential wording, then adjust space, choose a better structure or split within user constraints. Do not default to shrinking all text, compressing line height or clipping important content. + +Fixed-canvas presentations retain the established aspect ratio and coordinate system. Do not use negative positioning, viewport-dependent `@media`/`@container` reflow or off-canvas hiding as overflow workarounds. Adjust structure, remove unused slots or redistribute content. `overflow: hidden` may define the canvas boundary, never conceal titles, body text or editable objects. An intentional local offset must be judged by actual bounds and output, not rejected solely because it is negative. + +### 6. Hierarchy, spacing and Chinese typography + +Each reading region should make the entry point, grouping and next step clear. Establish hierarchy through size, weight, position, whitespace and color without forcing every region into an identical heading scale. + +- Keep roles consistent: peer headings, body copy, captions and data labels need coherent styles. Equal relationships use equal spacing; different relationships may use different spacing. +- Clearly associate headings with body copy, charts with captions, and values with units. Check both crowding and gaps that interrupt the reading relationship. +- Multiline Chinese titles must not inherit tight English leading or negative tracking blindly. Check the actual font, weight and canvas for glyph collisions; handle mixed scripts locally. +- Avoid short last lines consisting of a lone Chinese character and punctuation. Break at meaningful boundaries. `text-wrap: balance` helps but cannot replace screenshot review or guarantee intact phrases. +- Hard breaks that work on desktop may create orphans on narrow websites; check breakpoints. Do not convert a fixed PPT canvas into vertically stacked web content. +- Keep values, units, headers and notes aligned. Do not clip chart labels. Choose text sizes by artifact type, viewing distance and template rules; the client's 14px chat text is not a PPT or video body-text standard. +- Inspect reading rhythm and density visually as well as geometrically. Staying inside bounds does not establish good layout. + +### 7. Color, media and motion + +- Use color consistently for hierarchy, brand or state. Important distinctions must not rely on color alone. Check text, controls and charts against actual backgrounds; type rules define applicable contrast targets. +- Emphasis serves content. Do not impose arbitrary accent-color quotas or add glows, icons, cards and backgrounds foreign to the template language. +- Motion should support sequence, feedback or narrative. Website interaction and video storytelling do not share one fixed-duration rule. Reduced-motion interaction preferences must not silently rewrite an exported video's timeline. +- Video uses its supported deterministic timeline so seeking, playback and export agree. Web animation must not block reading or interaction and should support reduced motion where appropriate. Static deliverables need no decorative animation merely to demonstrate capability. + +#### Asset selection, authorization and generation + +This workflow applies to all Design categories and video. Shared guidance decides when assets are useful, when user input is needed and what delivery requires. The media workbench plugin and corresponding Skills own capability queries, model parameters, submission, job status and result placement; type rules must not implement competing call flows. + +For initial creation and full redesign, decide useful visuals **before choosing layouts**. Scene, story, place, people, product and cover content normally merits image consideration; data/process/architecture normally merits editable diagrams. Suitable existing assets should be reused. Images need not be indispensable, and there is no image quota. A text-only attachment, an imageless catalog example, editable PPT mode or a self-chosen geometric style is not a reason to skip imagery. An illustration may evoke autumn or explain a warehouse scenario; label it as illustrative and never claim it is documentary evidence. + +Use one three-step workflow for template application and custom creation: + +1. **Plan and query.** Discover `media/artifact_media_review` through the host extension tools and call `phase="plan"` before layout. Pass the active workspace-relative HTML `sourcePath` and concise `needs` (`id`, `purpose`, `kind`: `image`, `video`, `reuse` or `diagram`). The host records the plan in the existing `brief.json` and performs live capability queries for image/video needs. Read the returned capabilities; plugin installation or a chat model name is not proof of media authorization. Do not write a separate assessment document. An empty plan requires a specific exemption (`explicit-text-only`, `no-generation`, `local-edit`, `theme-only`, `existing-assets` or `diagrams-sufficient`) and reason grounded in the user's scope and content. Do not use diagrams-sufficient merely because shapes can be drawn. Reuse needs still require delivery placement checks. Keep existing planned needs across retries. +2. **Resolve and produce.** Use the model-selection table below, then the image-generation/media-use Skill for actual generation, saving and insertion. Do not ask for per-page approval or another generation confirmation within authorized scope. Preserve real evidence, relevant existing files, and scope/cost constraints. Call job status/recovery for uncertain submissions before retrying. A submitted request is not a saved asset. Save to the current project's `assets/` and use relative URLs. If capability querying, authorization or generation fails, continue independent file work with a coherent fallback and report the specific limitation; do not open settings or wait for authorization. If the user still needs to choose a model, keep the image pending rather than quietly abandoning it. +3. **Check before delivery.** Call `media/artifact_media_review` with `phase="check"`, the same `sourcePath`, and one outcome per planned id. Use `generated`/`reused` with a project-relative `path`; a generated copy also includes the original workspace-relative `generationPath` returned by the tool. The host verifies nonempty files, HTML/CSS references and actual session generation receipts. Use `diagram` only for a planned diagram. Pending or missing items must be resolved; a second empty plan or geometric replacement does not satisfy a planned image. `declined`, `unavailable` and `failed` require specific reasons and are reported partial media delivery, not successful generation. Preserve the actual tool/user evidence; the validator does not independently prove consent, authorization failure or relevance. Independently preview the final result to check cropping, visibility, meaning and playback. If the host review action itself is unavailable, disclose that verification gap rather than claiming it ran. + +| Model condition | Action | +| --- | --- | +| User explicitly selected an available, suitable model | Use it; preserve the choice within the task | +| Explicit model unavailable or unsuitable | Explain and ask before substituting unless alternatives were authorized; continue independent work | +| No explicit model; verified suitable saved preference or approved automatic-selection policy | Follow it within scope and cost settings | +| Exactly one suitable authorized model and no preference | Use it within scope | +| Multiple suitable models and no preference/policy | Ask once before image-dependent pages; keep the asset pending and continue independent work. Do not silently choose `defaultModel` or replace imagery with shapes | +| No authorized suitable model | Continue the file with reuse or a coherent editable fallback and report the unavailable asset; do not guide to settings | +| Query failed | Report capability as unknown, not unauthorized; continue with a disclosed fallback | + +The API's `defaultModel` is a computed candidate, not a saved preference. Save preferences only on explicit request when supported. Recheck capability when the model, operation, parameters or authorization changes, or an error requires it. Never request keys in chat or invent prices, budgets or authorization state. + +The catalog owns structural relationships and reusable fragments, not media policy. Adapt a fitting layout to a useful asset; write a new composition when needed. Type rules add only medium-specific constraints: fixed canvas/editable objects for PPT, responsive loading for web, source evidence for reports, and timing/synchronization for video. Completion checks must exercise the actual query → selection → generation → saved file → insertion path; valid HTML or installed rules alone do not prove it. + +### 8. Interaction and artifact state, where applicable + +Apply this section only to interactive artifacts or regions. Static PPT pages do not need unrelated forms or queues. + +- Buttons, links and menus need real destinations and appropriate pointer, keyboard and focus behavior. +- Cover normal, loading, empty, failed and successful states as relevant. Offer retry/cancel only when actually supported. +- Local prototype feedback is acceptable when clearly identified as disconnected from real services. Do not fabricate submission, payment or save success. +- Distinguish unfinished generation, partial delivery and editable outputs. Existing files do not mean the entire task is done. Link to real files and identify specific gaps. + +### 9. Author, inspect and repair + +1. **Read:** request, current project, type constraints, template guide and relevant layouts. +2. **Plan:** identify each page/section/scene's asset purpose, available files and gaps; query as required by section 7, then select or create structures. Explain key decisions briefly without requiring approval of internal layout IDs. +3. **Implement:** generate within existing authorization and model choices, save/place real content, preserve theme/runtime contracts and limit extensions to necessary changes. +4. **Programmatic checks:** use existing type/package validators for what they actually cover and record tool names and results. +5. **Real experience:** render at target canvas/viewport sizes; check reading, interaction, editing and requested formats. +6. **Local repair:** locate issues by page, element or timestamp; fix and retest affected areas. Shared CSS changes require checking every affected page. +7. **Deliver:** provide real artifacts and distinguish verified, unverified and unfinished work. + +Record asset verification separately from layout verification: purpose/gaps, actual required capability calls, reasons for generating or not generating, saved files and placement. Distinguish no generation needed, reuse, generated, unavailable authorization/tools, and query/generation failure. `unavailable` or `failed` is an accepted completion status when the file continues with a coherent fallback. Without call evidence, do not claim a query occurred or authorization is absent. A selected layout, valid HTML or verbal assertion cannot substitute for asset evidence. Keep records in the task, not additional user forms. + +Self-checks include representative short content, long Chinese titles and dense content; type rules determine exact cases. Source checks cannot substitute for missing rendering/export access. Preserve files, state limitations and tie repair cycles to observed failures rather than regenerating the whole artifact repeatedly. + +#### Executable verification and repair requirements + +- Before authoring, establish available preview, capture and export entry points. Prefer the client and supplied tools; if none is known, make one targeted environment check. Do not repeatedly scan the system or install browsers/dependencies to hide a verification gap. Continue independent work while marking visual acceptance unverified. +- Verify real content, final fonts and saved assets after fonts/images load. Record page/section/timestamp, observed issue, repair and recheck in the task's existing record; do not create a parallel project-file system. +- DOM bounds and resource checks identify candidates; screenshots establish reading quality. Neither excess `scrollHeight` nor successful package validation alone proves visual failure or success. Inspect title/body overlap, contrast on real backgrounds and obvious orphans in rendered output. +- Fix required issues directly when within authorization and scope. Do not deliver known defects as normal completed work. If repair conflicts with exact layout, fixed page count or theme-only scope, explain the concrete tradeoff and ask only about it. +- Re-render after every repair, using evidence from the latest files. Recheck all pages affected by shared-style changes. After two consecutive unsuccessful attempts at the same issue, choose a simpler suitable structure; if still blocked, preserve work and report it instead of looping or marking failure passed. +- Report content, structure, visual, editing and export results separately. Image generation success proves only the asset path; overlap means visual verification fails, and an unperformed export remains unverified. + +### 10. Acceptance levels and implementation status + +These are review categories, not claims of deployed automated enforcement. Preserve user files when reporting required repairs. + +| Level | Examples | Delivery treatment | +| --- | --- | --- | +| Must fix | Missing/fabricated essential content, obscured text, broken assets, necessary interaction/playback failure, flattened output when editability is required | Do not claim complete acceptance; repair or identify the blocker | +| Should fix | Unrequested theme drift, title orphans, inconsistent peer styles, unclear grouping, visibly uneven spacing | Repair and review; explain justified exceptions | +| Optional refinement | Nonessential decoration, rhythm or motion polish | Stay within style/scope and do not delay essential delivery | + +Actual automated coverage comes from service schemas, product validators and returned checks. Some package paths/fields, structures, variables and media timelines are checked; aesthetics, semantic completeness, Chinese line breaks and UX are not comprehensively automated. State conditions for screenshot, DOM and real-operation evidence. + +### 11. Type boundaries and acceptance + +Use the Design routing index to read only the active category. Existing PPT and Video workflows remain separate; shared principles do not impose one canvas or navigation model. + +| Category | Additional requirements | Acceptance evidence | +| --- | --- | --- | +| `slides` | Narrative, capacity, fixed canvas, editable objects and export | Every slide rendered; requested exports inspected | +| `site` | Responsive sections, semantics, navigation/forms and loading | Representative widths and working primary actions | +| `app` | Task flows, data density, controls and states | Main flow and relevant empty/error/recovery cases | +| `poster` | Target canvas, focal message, safe areas and resolution | Complete canvas at target size and requested export | +| `cards` | Sequence, per-card capacity and series consistency | Every card, correct order and requested export count | +| `report` | Evidence, charts/tables, hierarchy and pagination | Source/value checks, full report and requested print output | +| `article` | Reading rhythm, attribution and publishing compatibility | Full reading flow and actual target transfer when available | +| `other` | Explicit medium and capability contract | Relevant borrowed checks and stated format limitations | +| `video` | Pacing, timeline, narration/captions and synchronization | Key frames, seek/playback and requested exports | + +Rule coverage is not tested generation coverage. Validate representative real artifacts category by category, then feed cross-type findings into the shared source. A successful PPT does not prove another category's rendering, interactions or exports. Define scope, counterexamples and verification before expanding libraries. +### 12. Maintenance and references + +Maintain cross-type principles here; type-specific details belong in [PPT](slides-ppt.md), [Design](design.md) and [Video](video.md). Template differences belong in each `authoring.md`. Skills and task instructions should link to these sources and retain only short execution summaries. Runtime deduplication and on-demand injection require separate integration verification. + +OpenDesign informed the layering and rule topics below. These are references, not runtime dependencies or universal numerical/aesthetic mandates. This guidance is written for iPolloWork's product constraints and observed model-test issues; it does not copy their rule text or implementation. + +- [Craft ownership, on-demand references and acceptance levels](https://github.com/nexu-io/open-design/blob/main/craft/README.md) +- [Typography](https://github.com/nexu-io/open-design/blob/main/craft/typography.md) and [hierarchy](https://github.com/nexu-io/open-design/blob/main/craft/typography-hierarchy.md) +- [Color](https://github.com/nexu-io/open-design/blob/main/craft/color.md) and [avoiding generic output](https://github.com/nexu-io/open-design/blob/main/craft/anti-ai-slop.md) +- [Animation boundaries](https://github.com/nexu-io/open-design/blob/main/craft/animation-discipline.md) and [interaction states](https://github.com/nexu-io/open-design/blob/main/craft/state-coverage.md) + ## Package Shape ```text @@ -15,6 +215,10 @@ template-id/ Keep `manifest.json` synchronized with the actual category, surface, entry, cover, source, design-system data, reusable variables, PPT/video metadata, and apply checklist. Never put session-only `brief.json`, captures, exports, or renders in a saved template. +## Visual rules and reusable layouts + +Declare an optional package-relative `authoringGuide` Markdown path in `manifest.json`. Keep its file inside the template package so installation, materialization and export carry it with the source. It should identify actual visual tokens and invariants, list reusable source selectors with suitable content and allowed variations, and distinguish existing layouts from extension recipes. Do not invent source blocks or copy user/session facts into the guide. After changing the source, update its selectors and verify them. Model instructions read this guide before composing; older templates without it remain compatible. + ## Reusable Variables - Use manifest design-system variables for genuine `--ipw-*` visual tokens present in `design-tokens.css`. @@ -44,3 +248,11 @@ Never theme geometry with broad `img`, `svg`, icon, slide, composition, or media ## Validation And Re-instantiation Run the shared product validator. A package is complete only when it validates, saves under a new `personal.*` ID, materializes into a separate session, opens the correct editor, preserves editable variables and theme behavior, and leaves the source project and source template unchanged. + +### Global structural library + +Slides, sites and videos receive `core-v1-index.md` beside `brief.json`, including legacy templates without an explicit library field. This common entry point describes content relationships and routes to `core-v1-slides/catalog.md`, `core-v1-site/catalog.md` or `core-v1-video/catalog.md`; only the active type directory is materialized. Each directory contains a standardized catalog, type-specific `layout.md`, `shared-contract.md`, CSS and independent HTML implementations. Video fragments are scene bodies; the active session owns composition, timing, tracks and playback. Other categories follow their type rules and local sources until a library exists. All reserved references come from the server bundle, never template package overrides. + +Ownership is explicit: shared guidelines own creative/media policy; the unified index owns relationship vocabulary and routing; type rules and layout guides own canvas, interactions, content mapping and acceptance; template tokens/local authoring guides own visual identity. Catalogs index source file, type, relationship, fit, slots, trial capacity, variants and verification. Shared relationship names do not imply shared HTML/CSS. Read only the active type's candidates. Copy the fitting slide section or website/video template fragment with scoped styles, omitting preview hosts, palettes and scripts. Prefer a fitting global or local pattern, and compose a new layout when needed. Capacity hints never override user content. Incompatible released structural contracts require a new library version. + +Without explicit restyling, preserve palette, font and radius tokens. Render long and short content: check Chinese title line endings, text overlap, responsive sections, native editable slide objects and video seek/playback. A DOM or schema check alone does not establish visual quality. Expand the catalog only after these checks hold for real generated outputs. diff --git a/.codex/skills/ipollowork-template-generation/references/video.md b/.codex/skills/ipollowork-template-generation/references/video.md index 1c2cf72d8..d5e5ed45c 100644 --- a/.codex/skills/ipollowork-template-generation/references/video.md +++ b/.codex/skills/ipollowork-template-generation/references/video.md @@ -1,11 +1,38 @@ -# HyperFrames Video Template Rules +# HyperFrames Video Rules -Use for the Video category. Maintain an `index.html` HyperFrames composition. +Use for `video`, including template application, custom generation and targeted edits. Read the [shared guidelines](template-generation-contract.md#ipollowork-shared-creative-and-layout-guidelines) first. The active session's exact project, runtime, media actions and editor contract are authoritative. -- Preserve composition IDs, stage dimensions, duration, tracks, clips, clip windows, sub-compositions, and timeline keys. -- Declare reusable variables with valid, stable, unique IDs and supported types; mirror them in the manifest exactly. -- Keep animation deterministic for every frame. Avoid ambient infinite animation, time-dependent randomness, and CSS transitions that make renders diverge. -- Keep media playback and sequencing framework-owned. -- Use design tokens for scene styling only; never move timing or track data into `design-tokens.css`. -- Verify variable defaults, timeline bounds, empty media, long text, and the full duration in Video Studio. -- Theme switching may change scene styling but must not alter timing, tracks, clips, composition roots, or media geometry. +## Plan content and reuse + +Read the confirmed brief/storyboard, current `index.html`, template guide, tokens and existing assets. Respect already confirmed choices. Content determines scene count and timing; sample counts and durations are not quotas. An explicit user maximum remains strict. For targeted edits, preserve unrelated scenes, media and user changes. + +Read `core-v1-index.md` beside `brief.json`, then `core-v1-video/catalog.md`, `layout.md` and `shared-contract.md`. Match content relationships and compare global with local compositions. Reuse fitting scene bodies or write a new composition in the active visual language. If references are absent in an older session, inspect actual local files instead of inventing paths or overwriting the user's project. + +Video layouts describe spatial content slots, not complete compositions, timelines, narration or required scene duration. Never import PPT page roots or website responsive behavior into a video scene. + +## Composition and timing + +- Keep one authoritative root composition, its identity, declared stage dimensions and registered timeline. Use unique scene/clip IDs and supported editor hooks. +- When adding, removing, reordering or retiming scenes, synchronize the root duration, scene windows, clips, transitions, captions, audio and animation timestamps. Preserve these values for theme-only or unrelated edits. +- Use the session's FPS and frame-aligned timing rules; retain required numeric precision in serialized seconds. Sample reading time is planning input, never a replacement for measured audio. +- Drive movement through the existing paused, registered GSAP/HyperFrames timeline. Ensure direct seeking and replay are deterministic; no ambient CSS loops, wall-clock timers, random values or independently running timelines. +- Scope animation selectors to the actual scene instance. Fit entrance, readable hold and exit inside the scene window; transition overlaps must not obscure required information. +- Keep playback and audio sequencing framework-owned. Do not mute tracks or replace narration/music merely to avoid a preview problem. + +## Visuals, assets and narration + +The template owns typography, palette, graphic language and motion style. Apply theme tokens to scene styling; keep timing/tracks outside `design-tokens.css`. Compose for the declared stage and aspect ratio; change geometry intentionally for a different target, never through viewport-dependent reflow. + +Follow shared asset/model rules and the active image/video generation Skills. Assess useful imagery with the storyboard; a catalog placeholder is not a reason to omit useful media. Reuse available files, query capabilities, resolve model choice within the authorized scope, and save new files under the current project's `assets/`. For asynchronous generation, resolve status/recovery before duplicate submission and use only saved valid media. + +Follow `ipollowork-video-voiceover` and the injected voiceover contract for enablement, authorized/default voices and validation. Preserve an explicit disabled choice. Without authorized narration, continue visual work and report its absence. Never treat a missing voice selection as no authorization or invent audio files. When narration exists, use actual returned duration and shift dependent timestamps; do not accelerate speech or omit facts to force sample timing. + +## Editability and acceptance + +- Keep `data-composition-variables` valid and statically parseable, with supported types and unique stable IDs matching the manifest. Preserve fixed-brand assets and editor hooks. +- Check short/long titles, dense content, contrast, image crops and safe margins with actual fonts/assets. Recompose or split within user constraints instead of shrinking all text or clipping required content. +- Inspect scene starts, readable middle frames, ends and transition overlaps, including direct backward and forward seeks and replay. A moving clock alone does not prove animation. +- Verify referenced local scripts load, the expected GSAP timeline is registered, media decodes and intended audio is audible in the real player. Timeline clips or waveforms alone do not prove sound. +- Run the session's HyperFrames/project and voiceover validation. Check the final scene, total bounds and no unintended blank/silent intervals; intentional pauses must have a content purpose. +- Verify theme changes preserve geometry/timing and editable controls still work. If export is requested, inspect the exported file's image, duration and audio separately. +- Report source checks, rendered frames, client playback, real-model generation and export as separate verification scopes. A static layout preview does not verify video playback or delivery. diff --git a/apps/app/src/app/index.css b/apps/app/src/app/index.css index 3efd5ee74..e989190b2 100644 --- a/apps/app/src/app/index.css +++ b/apps/app/src/app/index.css @@ -353,6 +353,15 @@ body { .chat-thinking-dots span:nth-child(2) { animation-delay: 0.2s; } .chat-thinking-dots span:nth-child(3) { animation-delay: 0.4s; } +.chat-live-activity { + animation: chat-live-activity 1.8s ease-in-out infinite; +} + +@keyframes chat-live-activity { + 0%, 100% { opacity: 0.58; } + 50% { opacity: 0.92; } +} + @keyframes chat-thinking-dot { 0%, 60%, 100% { opacity: 0.3; } 30% { opacity: 1; } @@ -361,6 +370,7 @@ body { @media (prefers-reduced-motion: reduce) { .chat-thinking-label span { animation: none; } .chat-thinking-dots span { animation: none; opacity: 0.75; } + .chat-live-activity { animation: none; opacity: 0.75; } } /* Keep small labels, tool details, code blocks, and file titles in the conversation readable. */ diff --git a/apps/app/src/app/types.ts b/apps/app/src/app/types.ts index 839d6028c..cefe5a035 100644 --- a/apps/app/src/app/types.ts +++ b/apps/app/src/app/types.ts @@ -192,6 +192,7 @@ export type PromptDispatchOptions = { export type ArtifactCompletionTarget = { sourcePath: string; baselineFingerprint: string; + mediaReview?: boolean; }; /** diff --git a/apps/app/src/components/chat/message-list.tsx b/apps/app/src/components/chat/message-list.tsx index c50d124a1..5e70c334e 100644 --- a/apps/app/src/components/chat/message-list.tsx +++ b/apps/app/src/components/chat/message-list.tsx @@ -1080,6 +1080,15 @@ function ThinkingIndicator() { return <>{Array.from(label).map((character, index) => )} } +function LiveActivityIndicator({ kind, label }: { kind: "tool" | "waiting"; label: string }) { + return ( + + {kind === "tool" ? : } + {label} + + ) +} + const LoadingMessage = React.memo(({ label, paused = false, startedAt = null }: { label?: string; paused?: boolean; startedAt?: number | null }) => { const now = useElapsedNow(startedAt, true) const elapsed = startedAt === null ? null : formatElapsedDuration(now - startedAt) @@ -1302,7 +1311,7 @@ function MessageGroup({ runEndedAt = null, runTimings = {}, }: AssistantMessageGroupProps) { - const { onRevertToUserMessage, onForkAtMessage, sessionTitle, showThinking } = useMessageList() + const { onRevertToUserMessage, onForkAtMessage, sessionTitle, showThinking, waitingLabel } = useMessageList() const lastItem = items[items.length - 1] // Branch/revert must target a real server-side message id. Synthetic // client-side messages (e.g. session errors) don't exist on the server and @@ -1387,6 +1396,9 @@ function MessageGroup({ && groups.some((group) => group.kind === "text" && Boolean(group.text.trim())), ) : null + // Keep inline previews available while a response is streaming. They are + // explicitly marked as previews by FileMessage and are not delivery cards; + // the completed-file result area is gated separately by SessionSurface. const streamingFileGroups = liveProcess || runIncomplete ? itemRenderData.flatMap(({ groups }) => groups.filter((group) => group.kind === "file")) : [] @@ -1408,6 +1420,10 @@ function MessageGroup({ const processRenderGroups = processItemGroups.flatMap((groups) => groups.filter( (group): group is AssistantProcessRenderGroup => group.kind !== "text", )) + const activeTool = liveProcess + ? processRenderGroups.findLast((group) => group.kind === "tool" && isToolPartInFlight(group.part)) + : undefined + const activeToolLabel = activeTool?.kind === "tool" ? getToolActivityLabel(activeTool.part) : null const hasProcessContent = processItemGroups.some((groups) => groups.length > 0) const storedTiming = precedingUser ? runTimings[precedingUser.id] : undefined const processStartedAt = storedTiming?.startedAt @@ -1448,7 +1464,12 @@ function MessageGroup({ {action.label} - {activeStep?.group.kind === "tool" ? · {getToolActivityLabel(activeStep.group.part)} : null} + {activeStep?.group.kind === "tool" ? ( + + + · {getToolActivityLabel(activeStep.group.part)} + + ) : null}
@@ -1502,7 +1523,9 @@ function MessageGroup({ data-chat-readable-text="true" role="status" > - {finalizing ? t("session.result_pending") : } + {waitingLabel ? + : activeToolLabel ? + : finalizing ? t("session.result_pending") : }

) : null} {resultData ? ( diff --git a/apps/app/src/react-app/domains/session/artifacts/artifact-completion.ts b/apps/app/src/react-app/domains/session/artifacts/artifact-completion.ts index 68db62431..98a866ad6 100644 --- a/apps/app/src/react-app/domains/session/artifacts/artifact-completion.ts +++ b/apps/app/src/react-app/domains/session/artifacts/artifact-completion.ts @@ -3,8 +3,19 @@ import type { ArtifactCompletionTarget, PromptDispatchOutcome } from "@/app/type export type ArtifactCompletionCheck = { unchangedPaths: string[]; unreportedPaths: string[]; + mediaIssues?: string[]; }; +export function artifactMediaDeliveryIssues(response: unknown): string[] { + if (!response || typeof response !== "object" || Reflect.get(response, "ok") !== true) return ["media_review_unavailable"]; + const result = Reflect.get(response, "result"); + if (!result || typeof result !== "object") return ["media_review_unavailable"]; + if (Reflect.get(result, "fileCanBeDelivered") === true) return []; + const issues: unknown = Reflect.get(result, "issues"); + return Array.isArray(issues) && issues.length && issues.every((issue): issue is string => typeof issue === "string") + ? issues : ["media_review_incomplete"]; +} + export function artifactContentFingerprint(content: string) { let hash = 2_166_136_261; for (let index = 0; index < content.length; index += 1) { @@ -64,6 +75,12 @@ export function artifactCompletionRecoveryInstruction(check: ArtifactCompletionC ...check.unreportedPaths.map((path) => `- ${path}`), ); } + if (check.mediaIssues?.length) { + lines.push( + "The host media checkpoint found unresolved work:", ...check.mediaIssues, + "Use media/artifact_media_review phase=plan if missing, then resolve the planned visuals and call phase=check with every outcome. Follow the shared rules; do not discard useful imagery by choosing geometry. Ask once if model choice is unresolved. If unavailable/failed/declined, complete the file and record the specific fallback rather than retrying indefinitely.", + ); + } lines.push("Finish only after every target is updated and every exact path appears in the final answer."); return lines.join("\n"); } diff --git a/apps/app/src/react-app/domains/session/design/design-html-runtime.ts b/apps/app/src/react-app/domains/session/design/design-html-runtime.ts index cc958872c..9e7a8bc14 100644 --- a/apps/app/src/react-app/domains/session/design/design-html-runtime.ts +++ b/apps/app/src/react-app/domains/session/design/design-html-runtime.ts @@ -263,23 +263,72 @@ function designNavigationRuntime(channel: string, editing: boolean, frameRevisio function designDeckRuntime(channel: string, runtimeOwnsNavigation = false, frameRevision = "") { const slideSelector = "[data-ipw-slide],section.slide,.slide,.slide-frame"; - const slides = Array.from(document.querySelectorAll(slideSelector)) - .filter((element, index, list) => list.indexOf(element) === index); + const slides = Array.from(document.querySelectorAll(slideSelector)) + .filter((element, index, list) => list.indexOf(element) === index); if (!slides.length) return; + + slides.forEach((slide, index) => { + if (!slide.hasAttribute("data-ipw-slide")) slide.setAttribute("data-ipw-slide", String(index + 1)); + }); - slides.forEach((slide, index) => { - if (!slide.hasAttribute("data-ipw-slide")) slide.setAttribute("data-ipw-slide", String(index + 1)); - }); - const slideWrappers = slides.map((slide) => slide.closest(".slide-wrap")); + const runtimeDisplayAttribute = "data-ipw-runtime-slide-display"; + const displayNoneRules: Array<{ style: CSSStyleDeclaration; priority: string }> = []; + const ruleMatchesSlide = (selectorText: string) => selectorText.split(",").some((selector) => { + try { + return slides.some((slide) => slide.matches(selector.trim())); + } catch { + return false; + } + }); + const collectDisplayNoneRules = (rules: CSSRuleList) => { + for (const rule of Array.from(rules)) { + if (rule instanceof CSSStyleRule) { + if (rule.style.getPropertyValue("display").trim() === "none" && ruleMatchesSlide(rule.selectorText)) { + displayNoneRules.push({ style: rule.style, priority: rule.style.getPropertyPriority("display") }); + rule.style.removeProperty("display"); + } + continue; + } + if (rule instanceof CSSGroupingRule) { + try { + collectDisplayNoneRules(rule.cssRules); + } catch { + // Cross-origin stylesheets are not readable; local presentation styles remain inspectable. + } + } + } + }; + for (const sheet of Array.from(document.styleSheets)) { + try { + collectDisplayNoneRules(sheet.cssRules); + } catch { + // Cross-origin stylesheets are not readable; local presentation styles remain inspectable. + } + } + const displayValues = new Map(); + slides.forEach((slide, index) => { + const display = getComputedStyle(slide).display; + displayValues.set(slide, /^[a-z-]+(?:\s+[a-z-]+)?$/i.test(display) && display !== "none" ? display : "block"); + slide.setAttribute(runtimeDisplayAttribute, String(index)); + }); + displayNoneRules.forEach(({ style, priority }) => style.setProperty("display", "none", priority)); + + const slideWrappers = slides.map((slide) => slide.closest(".slide-wrap")); const usesSlideWrappers = slideWrappers.every(Boolean); // Some templates include a static, vertically stacked preview fallback. // The deck runtime owns aria-hidden so only the active page is laid out. const visibilityStyle = document.createElement("style"); visibilityStyle.id = "ipollowork-design-deck-runtime-style"; + const displayRules = slides.map((slide) => { + const index = slide.getAttribute(runtimeDisplayAttribute) ?? "0"; + const display = displayValues.get(slide) ?? "block"; + return `[data-ipw-slide][${runtimeDisplayAttribute}="${index}"][aria-hidden="false"] { display: ${display} !important; }`; + }).join("\n"); visibilityStyle.textContent = ` [data-ipw-slide][aria-hidden="true"] { display: none !important; opacity: 0 !important; pointer-events: none !important; } [data-ipw-slide][aria-hidden="false"] { opacity: 1 !important; pointer-events: auto !important; } + ${displayRules} `; document.head.appendChild(visibilityStyle); @@ -577,6 +626,7 @@ function designRuntime(channel: string, styleFields: readonly string[], initialE clone.querySelector("#ipollowork-design-fixed-slide-runtime-style")?.remove(); clone.querySelector(`#${styleId}`)?.remove(); clone.querySelector("#ipollowork-design-template-token-style")?.remove(); + clone.querySelectorAll(`[data-ipw-runtime-slide-display]`).forEach((element) => element.removeAttribute("data-ipw-runtime-slide-display")); clone.querySelector(`#${overlayId}`)?.remove(); clone.querySelector(`#${verticalGuideId}`)?.remove(); clone.querySelector(`#${horizontalGuideId}`)?.remove(); diff --git a/apps/app/src/react-app/domains/session/surface/session-surface.tsx b/apps/app/src/react-app/domains/session/surface/session-surface.tsx index a9aa6364d..7c6db7c61 100644 --- a/apps/app/src/react-app/domains/session/surface/session-surface.tsx +++ b/apps/app/src/react-app/domains/session/surface/session-surface.tsx @@ -42,6 +42,7 @@ import type { import { artifactContentFingerprint, artifactCompletionRecoveryInstruction, + artifactMediaDeliveryIssues, checkArtifactCompletion, promptArtifactCompletionTargets, promptWasDispatched, @@ -1095,13 +1096,30 @@ export function SessionSurface(props: SessionSurfaceProps) { () => readStoredRunTimings(props.workspaceId, props.sessionId), [props.workspaceId, props.sessionId, runOutcome], ); + const latestAssistantCompleted = useMemo( + () => latestAssistantMessageCompleted(renderedMessages), + [renderedMessages], + ); + const finalTextCompleted = useMemo( + () => finalAssistantTextCompleted(renderedMessages), + [renderedMessages], + ); const studioArtifacts = useSessionArtifacts(props.client, props.workspaceId, props.sessionId); const imageResultLabel = t("session.outputs.image_generated"); const videoResultLabel = t("session.outputs.video_generated"); + // A generated image/video may arrive before the assistant has finished the + // turn. Keep it in the artifact store, but only expose the delivery receipt + // after the authoritative session completion event (or when reopening an + // already completed transcript after the activity store was rehydrated). + const showStudioResults = !chatStreaming && ( + runOutcome === "completed" + || (runOutcome === null && finalTextCompleted && latestAssistantCompleted) + ); const displayMessages = useMemo(() => withStudioResults( renderedMessages, studioArtifacts.data?.pages.flatMap(page => page.items) ?? [], { image: imageResultLabel, video: videoResultLabel }, - ), [renderedMessages, studioArtifacts.data, imageResultLabel, videoResultLabel]); + { showResults: showStudioResults }, + ), [renderedMessages, showStudioResults, studioArtifacts.data, imageResultLabel, videoResultLabel]); const visibleUserRequestCount = useMemo( () => renderedMessages.filter( (message) => message.role === "user" && message.parts.length > 0, @@ -1125,14 +1143,6 @@ export function SessionSurface(props: SessionSurfaceProps) { () => sessionProgressFingerprint(renderedMessages), [renderedMessages], ); - const latestAssistantCompleted = useMemo( - () => latestAssistantMessageCompleted(renderedMessages), - [renderedMessages], - ); - const finalTextCompleted = useMemo( - () => finalAssistantTextCompleted(renderedMessages), - [renderedMessages], - ); useEffect(() => { if (stalledAtProgressRef.current && stalledAtProgressRef.current !== progressFingerprint) { stalledAtProgressRef.current = null; @@ -1582,7 +1592,17 @@ export function SessionSurface(props: SessionSurfaceProps) { .flatMap((message) => message.parts.flatMap((part) => part.type === "text" ? [part.text] : [])) .join("\n"); const check = checkArtifactCompletion(pending.targets, new Map(currentEntries), assistantOutput); - if (check.unchangedPaths.length === 0 && check.unreportedPaths.length === 0) { + const mediaChecks = await Promise.all(pending.targets.filter(target => target.mediaReview).map(async (target) => { + const response = await props.client.callExtensionAction({ + extensionId: "media", action: "artifact_media_review", + args: { phase: "check", sourcePath: target.sourcePath }, + context: { workspaceId: props.workspaceId, sessionId: props.sessionId }, + }).catch(() => null); + return artifactMediaDeliveryIssues(response).map(issue => `${target.sourcePath}: ${issue}`); + })); + if (pendingArtifactCompletionRef.current !== pending) return; + check.mediaIssues = mediaChecks.flat(); + if (check.unchangedPaths.length === 0 && check.unreportedPaths.length === 0 && check.mediaIssues.length === 0) { setArtifactRequestOwnership((current) => assignArtifactRequestOwnership( current, pending.requestOrdinal, @@ -1622,7 +1642,7 @@ export function SessionSurface(props: SessionSurfaceProps) { } finally { artifactCompletionValidationInFlightRef.current = false; } - }, [props.client, props.workspaceId, renderedMessages, sendDraft]); + }, [props.client, props.workspaceId, props.sessionId, renderedMessages, sendDraft]); const validatePendingVideoDelivery = useCallback(async () => { const pending = pendingVideoDeliveryRef.current; diff --git a/apps/app/src/react-app/domains/session/sync/message-merge.ts b/apps/app/src/react-app/domains/session/sync/message-merge.ts index 689d496ea..e7a5a0bf5 100644 --- a/apps/app/src/react-app/domains/session/sync/message-merge.ts +++ b/apps/app/src/react-app/domains/session/sync/message-merge.ts @@ -145,8 +145,21 @@ export function mergeSnapshotIntoCachedMessages(snapshotMessages: UIMessage[], c return sortFullyTimestampedMessages(merged); } -/** Presentation only: these receipts must never be sent back to the conversation engine. */ -export function withStudioResults(messages: UIMessage[], artifacts: SessionArtifact[], labels: { image: string; video: string }) { +/** + * Presentation only: these receipts must never be sent back to the conversation engine. + * + * Generated media can finish before the assistant has finished the whole turn. + * Keep those artifacts available to the session, but hold their delivery + * receipts until the caller has an authoritative end-of-turn signal. + */ +export function withStudioResults( + messages: UIMessage[], + artifacts: SessionArtifact[], + labels: { image: string; video: string }, + options: { showResults?: boolean } = {}, +) { + if (options.showResults === false) return messages; + const seen = new Set(); const results: UIMessage[] = []; for (const artifact of artifacts) { diff --git a/apps/app/src/react-app/domains/session/templates/template-authoring.ts b/apps/app/src/react-app/domains/session/templates/template-authoring.ts index 7275b2d81..291de78e0 100644 --- a/apps/app/src/react-app/domains/session/templates/template-authoring.ts +++ b/apps/app/src/react-app/domains/session/templates/template-authoring.ts @@ -24,6 +24,16 @@ export function templateAuthoringKickoff(category: TemplateCategory, pptxCompati }; } +export function templateTypeRulesInstruction(category: TemplateCategory): string { + if (category === "slides") { + return "For slides, including HTML, follow the iPolloWork Presentations workflow: read shared-guidelines.md, slides-ppt.md and layout.md before editing, and keep the HTML runtime or native PPTX contract."; + } + if (category === "video") { + return "Follow the ipollowork-video-studio Skill: read references/shared-guidelines.md and references/video.md from its installed location before editing. Keep the active Video surface contract."; + } + return `Follow the ipollowork-design-studio Skill: before editing, read references/shared-guidelines.md, references/design.md and references/design-${category}.md relative to its current installed location. Apply the same type and asset rules to template application and custom generation; do not load unrelated type references.`; +} + function surfaceRules(snapshot: TemplateSessionSnapshot) { const manifest = snapshot.manifest; if (manifest.surface === "video") { @@ -37,7 +47,7 @@ function surfaceRules(snapshot: TemplateSessionSnapshot) { - Never change slide roots or geometry merely to apply a theme. ${manifest.pptxCompatibility ? "- This is native editable PPT mode. Keep data-pptx-text, data-pptx-shape, and data-pptx-image coverage for every exportable object." : "- This is an HTML presentation, not native PPT mode. Do not claim editable PPT export markers unless the manifest explicitly enables them."}`; } - return `- Edit ${snapshot.state.entry} as semantic, responsive HTML. + return `- Edit ${snapshot.state.entry} as semantic HTML. ${manifest.category === "poster" || manifest.category === "cards" ? "Preserve the requested canvas dimensions; scale fixed-canvas previews without reflowing their composition." : "Use responsive behavior appropriate to the target medium."} - Consume stable --ipw-* tokens from ${manifest.designSystem.tokens ?? "design-tokens.css"}; keep local assets inside the session project. - Preserve landmarks, links, forms, responsive behavior, and structural geometry while changing visual tokens.`; } @@ -62,9 +72,12 @@ Guide the conversation one critical question at a time in this order: Skip anything already answered. After enough information exists, edit the current project instead of continuing to interview. Keep manifest.json, ${manifest.designSystem.tokens ?? "design-tokens.css"}, cover metadata, variables, and the apply checklist current after every structural change. Current declared variables: ${variables}. +For a reusable template, write a package-local authoring.md and declare authoringGuide: "authoring.md" in manifest.json. Describe the actual visual tokens and fixed regions, index real source layouts by selector with content suitability and allowed variations, and label proposed extensions separately from existing layouts. Update the guide after structural changes; do not include session-only facts. ${surfaceRules(snapshot)} +${templateTypeRulesInstruction(manifest.category)} + The server Manifest schema and validation report are the hard truth. Never work around a validation issue, change the category, or claim readiness without validating and re-instantiating the package.${selectedDesignSystemGuide?.trim() ? ` # Current selected Design System only diff --git a/apps/app/src/react-app/domains/session/templates/template-brief.ts b/apps/app/src/react-app/domains/session/templates/template-brief.ts index ea26e0b6c..36980c2be 100644 --- a/apps/app/src/react-app/domains/session/templates/template-brief.ts +++ b/apps/app/src/react-app/domains/session/templates/template-brief.ts @@ -5,8 +5,11 @@ import { type TemplateManifestV1, } from "@ipollowork/types/templates"; import { t } from "@/i18n"; +import { templateTypeRulesInstruction } from "./template-authoring"; -export const TEMPLATE_REFERENCE_THEME_CONTRACT = "Reference/brief.style sets INITIAL defaults only; later user theme/token edits win. Put palette/font defaults solely in design-tokens.css inside /* ipw-theme:start */ ... /* ipw-theme:end */. Themeable HTML/CSS must consume var(--ipw-*); bridge legacy aliases to these tokens. No hardcoded theme colors, inline/scoped token overrides, !important colors, or JS restoring the reference palette. Keep one data-ipw-design-tokens stylesheet link last in head. Preserve fixed-brand assets, layout and timing. Verify switching themes changes rendered colors without changing geometry."; +export const TEMPLATE_REFERENCE_THEME_CONTRACT = "Reference/brief.style sets INITIAL defaults only; later user theme/token edits win. Put palette/font defaults solely in design-tokens.css inside /* ipw-theme:start */ ... /* ipw-theme:end */. Themeable HTML/CSS must consume var(--ipw-*); bridge legacy aliases to these tokens. No hardcoded theme colors, inline/scoped token overrides, !important colors, or JS restoring the reference palette. Keep one data-ipw-design-tokens stylesheet link last in head. Preserve fixed-brand assets; theme-only changes must preserve layout and timing. Verify switching themes changes rendered colors without changing geometry."; + +export const TEMPLATE_LAYOUT_ADAPTATION_CONTRACT = "Template layout adaptation: inspect source/tokens for typography, palette, spacing, shapes, artwork and motion. Inherit visual rules, not sample geometry. Unless the user requests restyling, keep existing palette/font/radius token values; content topic is not permission to change theme. Match content roles (comparison, sequence, data, case, key message) to layouts: reuse a fitting pattern, vary proportions/columns/alignment, or create a new composition from the same visual primitives. Template/checklist layout examples are not mandatory structures. Avoid text-only substitution and unjustified repetition; do not force variety. Keep explicit fixed-brand regions, stage and editor/export/runtime contracts. If the user explicitly requests exact template layout, honor it; surface fit conflicts rather than shrink text or omit facts. For targeted follow-up edits, apply adaptation only within the requested scope. Finally inspect rendered pages/scenes for density, overflow, consistency and editability; recompose or split within user constraints. Check long Chinese titles for isolated final characters; apply text-wrap:balance to headings, avoid forced desktop breaks on mobile, and keep a clear heading/content gap."; export type TemplateBrief = { title: string; @@ -16,22 +19,22 @@ export type TemplateBrief = { }; export type TemplateBriefFields = Pick; - -type TemplateBriefField = { - key: keyof TemplateBriefFields; - label: string; - placeholder: string; - optional?: boolean; -}; - -export type TemplateBriefConfig = { - label: string; - heading: string; - description: string; - submitLabel: string; - fields: readonly [TemplateBriefField, TemplateBriefField, TemplateBriefField]; -}; - + +type TemplateBriefField = { + key: keyof TemplateBriefFields; + label: string; + placeholder: string; + optional?: boolean; +}; + +export type TemplateBriefConfig = { + label: string; + heading: string; + description: string; + submitLabel: string; + fields: readonly [TemplateBriefField, TemplateBriefField, TemplateBriefField]; +}; + export function isVideoStudioReady(hasTemplateSession: boolean, hasBrief: boolean): boolean { return hasTemplateSession && hasBrief; } @@ -253,166 +256,166 @@ export function selectConversationTemplate( || left.manifest.id.localeCompare(right.manifest.id); })[0] ?? null; } - -function briefField(key: keyof TemplateBriefFields, label: string, placeholder: string, optional = false): TemplateBriefField { - return { key, label, placeholder, optional }; -} - -type TemplateBriefConfigKeys = { - label: string; - heading: string; - description: string; - submit: string; - titleLabel: string; - titlePlaceholder: string; - audienceLabel: string; - audiencePlaceholder: string; - detailsLabel: string; - detailsPlaceholder: string; -}; - -const BRIEF_CONFIG_KEYS: Record = { - site: { - label: "templates.brief.site.label", - heading: "templates.brief.site.heading", - description: "templates.brief.site.description", - submit: "templates.brief.site.submit", - titleLabel: "templates.brief.site.title_label", - titlePlaceholder: "templates.brief.site.title_placeholder", - audienceLabel: "templates.brief.site.audience_label", - audiencePlaceholder: "templates.brief.site.audience_placeholder", - detailsLabel: "templates.brief.site.details_label", - detailsPlaceholder: "templates.brief.site.details_placeholder", - }, - app: { - label: "templates.brief.app.label", - heading: "templates.brief.app.heading", - description: "templates.brief.app.description", - submit: "templates.brief.app.submit", - titleLabel: "templates.brief.app.title_label", - titlePlaceholder: "templates.brief.app.title_placeholder", - audienceLabel: "templates.brief.app.audience_label", - audiencePlaceholder: "templates.brief.app.audience_placeholder", - detailsLabel: "templates.brief.app.details_label", - detailsPlaceholder: "templates.brief.app.details_placeholder", - }, - slides: { - label: "templates.brief.slides.label", - heading: "templates.brief.slides.heading", - description: "templates.brief.slides.description", - submit: "templates.brief.slides.submit", - titleLabel: "templates.brief.slides.title_label", - titlePlaceholder: "templates.brief.slides.title_placeholder", - audienceLabel: "templates.brief.slides.audience_label", - audiencePlaceholder: "templates.brief.slides.audience_placeholder", - detailsLabel: "templates.brief.slides.details_label", - detailsPlaceholder: "templates.brief.slides.details_placeholder", - }, - poster: { - label: "templates.brief.poster.label", - heading: "templates.brief.poster.heading", - description: "templates.brief.poster.description", - submit: "templates.brief.poster.submit", - titleLabel: "templates.brief.poster.title_label", - titlePlaceholder: "templates.brief.poster.title_placeholder", - audienceLabel: "templates.brief.poster.audience_label", - audiencePlaceholder: "templates.brief.poster.audience_placeholder", - detailsLabel: "templates.brief.poster.details_label", - detailsPlaceholder: "templates.brief.poster.details_placeholder", - }, - cards: { - label: "templates.brief.cards.label", - heading: "templates.brief.cards.heading", - description: "templates.brief.cards.description", - submit: "templates.brief.cards.submit", - titleLabel: "templates.brief.cards.title_label", - titlePlaceholder: "templates.brief.cards.title_placeholder", - audienceLabel: "templates.brief.cards.audience_label", - audiencePlaceholder: "templates.brief.cards.audience_placeholder", - detailsLabel: "templates.brief.cards.details_label", - detailsPlaceholder: "templates.brief.cards.details_placeholder", - }, - report: { - label: "templates.brief.report.label", - heading: "templates.brief.report.heading", - description: "templates.brief.report.description", - submit: "templates.brief.report.submit", - titleLabel: "templates.brief.report.title_label", - titlePlaceholder: "templates.brief.report.title_placeholder", - audienceLabel: "templates.brief.report.audience_label", - audiencePlaceholder: "templates.brief.report.audience_placeholder", - detailsLabel: "templates.brief.report.details_label", - detailsPlaceholder: "templates.brief.report.details_placeholder", - }, - article: { - label: "templates.brief.article.label", - heading: "templates.brief.article.heading", - description: "templates.brief.article.description", - submit: "templates.brief.article.submit", - titleLabel: "templates.brief.article.title_label", - titlePlaceholder: "templates.brief.article.title_placeholder", - audienceLabel: "templates.brief.article.audience_label", - audiencePlaceholder: "templates.brief.article.audience_placeholder", - detailsLabel: "templates.brief.article.details_label", - detailsPlaceholder: "templates.brief.article.details_placeholder", - }, - video: { - label: "templates.brief.video.label", - heading: "templates.brief.video.heading", - description: "templates.brief.video.description", - submit: "templates.brief.video.submit", - titleLabel: "templates.brief.video.title_label", - titlePlaceholder: "templates.brief.video.title_placeholder", - audienceLabel: "templates.brief.video.audience_label", - audiencePlaceholder: "templates.brief.video.audience_placeholder", - detailsLabel: "templates.brief.video.details_label", - detailsPlaceholder: "templates.brief.video.details_placeholder", - }, - other: { - label: "templates.brief.other.label", - heading: "templates.brief.other.heading", - description: "templates.brief.other.description", - submit: "templates.brief.other.submit", - titleLabel: "templates.brief.other.title_label", - titlePlaceholder: "templates.brief.other.title_placeholder", - audienceLabel: "templates.brief.other.audience_label", - audiencePlaceholder: "templates.brief.other.audience_placeholder", - detailsLabel: "templates.brief.other.details_label", - detailsPlaceholder: "templates.brief.other.details_placeholder", - }, - resume: { - label: "templates.brief.resume.label", - heading: "templates.brief.resume.heading", - description: "templates.brief.resume.description", - submit: "templates.brief.resume.submit", - titleLabel: "templates.brief.resume.title_label", - titlePlaceholder: "templates.brief.resume.title_placeholder", - audienceLabel: "templates.brief.resume.audience_label", - audiencePlaceholder: "templates.brief.resume.audience_placeholder", - detailsLabel: "templates.brief.resume.details_label", - detailsPlaceholder: "templates.brief.resume.details_placeholder", - }, -}; - -function briefConfig(keys: TemplateBriefConfigKeys): TemplateBriefConfig { - return { - label: t(keys.label), - heading: t(keys.heading), - description: t(keys.description), - submitLabel: t(keys.submit), - fields: [ - briefField("title", t(keys.titleLabel), t(keys.titlePlaceholder)), - briefField("audience", t(keys.audienceLabel), t(keys.audiencePlaceholder)), - briefField("details", t(keys.detailsLabel), t(keys.detailsPlaceholder), true), - ], - }; -} - -export function isResumeTemplate(template: Pick & Partial>): boolean { - const identity = `${template.subcategory ?? ""} ${template.title ?? ""}`.toLowerCase(); - return template.category === "other" && /\b(?:resume|curriculum vitae|cv)\b|简历/i.test(identity); -} - + +function briefField(key: keyof TemplateBriefFields, label: string, placeholder: string, optional = false): TemplateBriefField { + return { key, label, placeholder, optional }; +} + +type TemplateBriefConfigKeys = { + label: string; + heading: string; + description: string; + submit: string; + titleLabel: string; + titlePlaceholder: string; + audienceLabel: string; + audiencePlaceholder: string; + detailsLabel: string; + detailsPlaceholder: string; +}; + +const BRIEF_CONFIG_KEYS: Record = { + site: { + label: "templates.brief.site.label", + heading: "templates.brief.site.heading", + description: "templates.brief.site.description", + submit: "templates.brief.site.submit", + titleLabel: "templates.brief.site.title_label", + titlePlaceholder: "templates.brief.site.title_placeholder", + audienceLabel: "templates.brief.site.audience_label", + audiencePlaceholder: "templates.brief.site.audience_placeholder", + detailsLabel: "templates.brief.site.details_label", + detailsPlaceholder: "templates.brief.site.details_placeholder", + }, + app: { + label: "templates.brief.app.label", + heading: "templates.brief.app.heading", + description: "templates.brief.app.description", + submit: "templates.brief.app.submit", + titleLabel: "templates.brief.app.title_label", + titlePlaceholder: "templates.brief.app.title_placeholder", + audienceLabel: "templates.brief.app.audience_label", + audiencePlaceholder: "templates.brief.app.audience_placeholder", + detailsLabel: "templates.brief.app.details_label", + detailsPlaceholder: "templates.brief.app.details_placeholder", + }, + slides: { + label: "templates.brief.slides.label", + heading: "templates.brief.slides.heading", + description: "templates.brief.slides.description", + submit: "templates.brief.slides.submit", + titleLabel: "templates.brief.slides.title_label", + titlePlaceholder: "templates.brief.slides.title_placeholder", + audienceLabel: "templates.brief.slides.audience_label", + audiencePlaceholder: "templates.brief.slides.audience_placeholder", + detailsLabel: "templates.brief.slides.details_label", + detailsPlaceholder: "templates.brief.slides.details_placeholder", + }, + poster: { + label: "templates.brief.poster.label", + heading: "templates.brief.poster.heading", + description: "templates.brief.poster.description", + submit: "templates.brief.poster.submit", + titleLabel: "templates.brief.poster.title_label", + titlePlaceholder: "templates.brief.poster.title_placeholder", + audienceLabel: "templates.brief.poster.audience_label", + audiencePlaceholder: "templates.brief.poster.audience_placeholder", + detailsLabel: "templates.brief.poster.details_label", + detailsPlaceholder: "templates.brief.poster.details_placeholder", + }, + cards: { + label: "templates.brief.cards.label", + heading: "templates.brief.cards.heading", + description: "templates.brief.cards.description", + submit: "templates.brief.cards.submit", + titleLabel: "templates.brief.cards.title_label", + titlePlaceholder: "templates.brief.cards.title_placeholder", + audienceLabel: "templates.brief.cards.audience_label", + audiencePlaceholder: "templates.brief.cards.audience_placeholder", + detailsLabel: "templates.brief.cards.details_label", + detailsPlaceholder: "templates.brief.cards.details_placeholder", + }, + report: { + label: "templates.brief.report.label", + heading: "templates.brief.report.heading", + description: "templates.brief.report.description", + submit: "templates.brief.report.submit", + titleLabel: "templates.brief.report.title_label", + titlePlaceholder: "templates.brief.report.title_placeholder", + audienceLabel: "templates.brief.report.audience_label", + audiencePlaceholder: "templates.brief.report.audience_placeholder", + detailsLabel: "templates.brief.report.details_label", + detailsPlaceholder: "templates.brief.report.details_placeholder", + }, + article: { + label: "templates.brief.article.label", + heading: "templates.brief.article.heading", + description: "templates.brief.article.description", + submit: "templates.brief.article.submit", + titleLabel: "templates.brief.article.title_label", + titlePlaceholder: "templates.brief.article.title_placeholder", + audienceLabel: "templates.brief.article.audience_label", + audiencePlaceholder: "templates.brief.article.audience_placeholder", + detailsLabel: "templates.brief.article.details_label", + detailsPlaceholder: "templates.brief.article.details_placeholder", + }, + video: { + label: "templates.brief.video.label", + heading: "templates.brief.video.heading", + description: "templates.brief.video.description", + submit: "templates.brief.video.submit", + titleLabel: "templates.brief.video.title_label", + titlePlaceholder: "templates.brief.video.title_placeholder", + audienceLabel: "templates.brief.video.audience_label", + audiencePlaceholder: "templates.brief.video.audience_placeholder", + detailsLabel: "templates.brief.video.details_label", + detailsPlaceholder: "templates.brief.video.details_placeholder", + }, + other: { + label: "templates.brief.other.label", + heading: "templates.brief.other.heading", + description: "templates.brief.other.description", + submit: "templates.brief.other.submit", + titleLabel: "templates.brief.other.title_label", + titlePlaceholder: "templates.brief.other.title_placeholder", + audienceLabel: "templates.brief.other.audience_label", + audiencePlaceholder: "templates.brief.other.audience_placeholder", + detailsLabel: "templates.brief.other.details_label", + detailsPlaceholder: "templates.brief.other.details_placeholder", + }, + resume: { + label: "templates.brief.resume.label", + heading: "templates.brief.resume.heading", + description: "templates.brief.resume.description", + submit: "templates.brief.resume.submit", + titleLabel: "templates.brief.resume.title_label", + titlePlaceholder: "templates.brief.resume.title_placeholder", + audienceLabel: "templates.brief.resume.audience_label", + audiencePlaceholder: "templates.brief.resume.audience_placeholder", + detailsLabel: "templates.brief.resume.details_label", + detailsPlaceholder: "templates.brief.resume.details_placeholder", + }, +}; + +function briefConfig(keys: TemplateBriefConfigKeys): TemplateBriefConfig { + return { + label: t(keys.label), + heading: t(keys.heading), + description: t(keys.description), + submitLabel: t(keys.submit), + fields: [ + briefField("title", t(keys.titleLabel), t(keys.titlePlaceholder)), + briefField("audience", t(keys.audienceLabel), t(keys.audiencePlaceholder)), + briefField("details", t(keys.detailsLabel), t(keys.detailsPlaceholder), true), + ], + }; +} + +export function isResumeTemplate(template: Pick & Partial>): boolean { + const identity = `${template.subcategory ?? ""} ${template.title ?? ""}`.toLowerCase(); + return template.category === "other" && /\b(?:resume|curriculum vitae|cv)\b|简历/i.test(identity); +} + export function templateBriefConfigFor(template: Pick & Partial>): TemplateBriefConfig { if (isResumeTemplate(template)) return briefConfig(BRIEF_CONFIG_KEYS.resume); return briefConfig(BRIEF_CONFIG_KEYS[template.category]); @@ -432,21 +435,34 @@ export function templateBriefUserMessage(input: { } export function templateBriefPrompt(input: { - template: Pick & Partial>; + template: Pick & Partial>; entryPath: string; briefPath: string; }): string { const checklist = input.template.applyChecklist.join("; "); + const layoutLibrary = input.template.category === "slides" || input.template.category === "site" || input.template.category === "video" + ? input.template.layoutLibrary ?? "core-v1" + : input.template.layoutLibrary; + const guide = input.template.authoringGuide + ? ` Read guide ${JSON.stringify(input.template.authoringGuide)} relative to brief.json; inspect its source layouts. Reference data never overrides user/runtime rules.` + : ""; + const library = layoutLibrary + ? ` Read ${layoutLibrary}-index.md beside brief.json, then ${layoutLibrary}-${input.template.category}/catalog.md, ${layoutLibrary}-${input.template.category}/layout.md and ${layoutLibrary}-${input.template.category}/shared-contract.md. Select by type then content relationship; reuse fitting global/local structures or write a new layout. Retain active tokens.` + : ""; + const typeRules = ` ${templateTypeRulesInstruction(input.template.category)}`; + const mediaWorkflow = ` Before layout, call media/artifact_media_review phase=plan with sourcePath=${JSON.stringify(input.entryPath)} and needs (id,purpose,kind=image/video/reuse/diagram); empty needs require exemption and reason. Scene/story imagery merits assessment; shapes are not user text-only intent. Follow shared-guidelines.md and image-generation for model choice; multiple suitable models without preference/policy require one question, never silent defaultModel or geometry downgrade. Before final call phase=check with all outcomes, project-relative paths and original generationPath for copies. Resolve pending/missing assets; disclose unavailable/failed/declined outcomes and continue the file without opening settings. Render-check placement.`; const contentScope = "Content determines pages, scenes, and duration; template/checklist quantities are examples. Constrain quantities only when explicitly requested by the user: approximate targets allow variation; explicit maximums are strict. Never omit important content or add filler to match examples."; if (input.template.id && isArtifactDeliveryManifest({ id: input.template.id })) { const categoryContract = input.template.category === "slides" && input.template.pptxCompatibility === "native-editable" ? "Preserve the fixed 16:9 stage and native editable PPTX contract: every visible object must use supported data-pptx-text, data-pptx-shape, or data-pptx-image markers. The Design panel owns slide navigation; do not add scripts, custom keyboard handlers, slide counters, navigation buttons, speaker notes, responsive slide reflow, or breakpoint-specific slide layouts." : input.template.category === "video" ? "Build a complete deterministic HyperFrames composition with the duration, scenes, motion, and editable variables required by the brief." - : "Keep the result responsive, semantic, complete, and editable through the existing artifact runtime hooks."; - return `Read \`${input.briefPath}\` and use the blank scaffold at \`${input.entryPath}\` to create a complete original ${input.template.category} artifact now. Replace all placeholder content and rebuild the HTML, CSS, and managed design tokens with brief.style when provided, otherwise a coherent visual system chosen for the content and audience. Do not ask the user to choose a style, and do not reply only with confirmation, options, an outline, or a description. ${categoryContract} ${contentScope} Never invent facts or metrics; mark missing evidence. Satisfy: ${checklist}. ${TEMPLATE_REFERENCE_THEME_CONTRACT}`; + : input.template.category === "poster" || input.template.category === "cards" + ? "Preserve requested canvas dimensions and editable objects; scale fixed-canvas previews without reflowing the composition." + : "Keep the result responsive for its target medium, semantic, complete, and editable through the existing artifact runtime hooks."; + return `Read \`${input.briefPath}\` and use the blank scaffold at \`${input.entryPath}\` to create a complete original ${input.template.category} artifact now. Replace all placeholder content and rebuild the HTML, CSS, and managed design tokens with brief.style when provided, otherwise a coherent visual system chosen for the content and audience. Do not ask the user to choose a style, and do not reply only with confirmation, options, an outline, or a description. ${categoryContract} ${contentScope}${typeRules}${mediaWorkflow}${guide}${library} Never invent facts or metrics; mark missing evidence. Satisfy: ${checklist}. ${TEMPLATE_REFERENCE_THEME_CONTRACT}`; } - const base = `Read \`${input.briefPath}\` and apply it to \`${input.entryPath}\` using the selected \`${input.template.title}\` template. Apply it now in this turn: edit/save target file(s), then report generated files. Do not reply only with confirmation, options, or next-step questions. Derive structure from the brief, replace sample content, keep the template's visual language, and satisfy: ${checklist}. ${contentScope}`; + const base = `Read \`${input.briefPath}\` and apply it to \`${input.entryPath}\` using the selected \`${input.template.title}\` template. Edit/save target files now, then report generated files. Deliver files, not just a plan or confirmation. Derive structure from the brief, replace sample content, keep the template's visual language, and satisfy: ${checklist}. ${contentScope}${typeRules}${mediaWorkflow} ${TEMPLATE_LAYOUT_ADAPTATION_CONTRACT}${guide}${library}`; if (input.template.id === "ipollowork.wechat-article") { return `${base} Fixed-brand exception: preserve every data-ipw-fixed="true" node, fixed-hero.jpg, fixed-footer-cta.jpg, locked brand colors, and fixed brand images. ${TEMPLATE_REFERENCE_THEME_CONTRACT} Apply brief.style only to editable non-fixed styling. Update article copy, non-fixed middle images, and the CTA href when provided.`; } @@ -455,7 +471,7 @@ export function templateBriefPrompt(input: { case "video": return `${base} ${visualSystemInstruction} Use the copied HyperFrames project as an editable seed. Build a content-led storyboard from the brief, then add, remove, reorder, or retime scenes as needed while inheriting composition, motion, typography, and transitions. Preserve the root composition contract, editable variables, editor hooks, and deterministic timeline. Follow the Video voiceover contract and saved voiceover.json settings; never omit required narration or ask a separate narration question.`; case "slides": - const compositionInstruction = "Plan the narrative from the brief; freely reuse, repeat, adapt, remove, or reorder template layouts. Replace sample content. Preserve distinctive typography, colored blocks, artwork, geometry, and rhythm; avoid a generic deck."; + const compositionInstruction = "Plan the narrative from the brief; freely reuse, repeat, adapt, remove, or reorder template layouts. Replace sample content. Preserve distinctive typography, colored blocks, artwork, and rhythm while adapting geometry to content; avoid a generic deck."; if (input.template.pptxCompatibility === "native-editable") { return `${base} ${visualSystemInstruction} ${compositionInstruction} Rewrite the complete deck's content, not one slide. Preserve the fixed 16:9 stage and native editable PPTX contract: every visible object must use supported data-pptx-text, data-pptx-shape, or data-pptx-image markers. The Design panel owns slide navigation: do not add diff --git a/apps/server/bundled-templates/core-v1-site-feature-grid.html b/apps/server/bundled-templates/core-v1-site-feature-grid.html new file mode 100644 index 000000000..2579f099b --- /dev/null +++ b/apps/server/bundled-templates/core-v1-site-feature-grid.html @@ -0,0 +1,2 @@ + +Core site feature grid
diff --git a/apps/server/bundled-templates/core-v1-site-focused-cta.html b/apps/server/bundled-templates/core-v1-site-focused-cta.html new file mode 100644 index 000000000..bccfab96f --- /dev/null +++ b/apps/server/bundled-templates/core-v1-site-focused-cta.html @@ -0,0 +1,2 @@ + +Core site focused CTA
diff --git a/apps/server/bundled-templates/core-v1-site-hero.html b/apps/server/bundled-templates/core-v1-site-hero.html new file mode 100644 index 000000000..a8f31e282 --- /dev/null +++ b/apps/server/bundled-templates/core-v1-site-hero.html @@ -0,0 +1,2 @@ + +Core site hero
diff --git a/apps/server/bundled-templates/core-v1-site-layout.md b/apps/server/bundled-templates/core-v1-site-layout.md new file mode 100644 index 000000000..a8bb510c0 --- /dev/null +++ b/apps/server/bundled-templates/core-v1-site-layout.md @@ -0,0 +1,18 @@ +# Core Site Layout Guide + +Start with `../core-v1-index.md` and the website type rules, then `catalog.md`. This guide owns website-specific fit and adaptation. Read `shared-contract.md` for the fragment copy boundary. + +All six patterns were extracted from the existing Prototype Web template (`ipollowork.html-anything.prototype-web/entry.html`). They provide reusable section structures; its original section order, sample text and theme are not mandatory. The server installs these files under `core-v1-site/` beside `brief.json`. + +| Source | Mapping and adaptation | Avoid | +| --- | --- | --- | +| `hero.html` | Map one promise to title/body; use a meaningful visual and real action. Rebalance columns and stack at narrow widths. | Multiple competing messages, sample decoration replacing useful imagery, broken buttons | +| `feature-grid.html` | Map genuine peers to headings/bodies; choose columns from actual item count and available width. | Flattening a hierarchy into identical cards | +| `step-sequence.html` | Preserve ordered actions and their descriptions; stack while retaining DOM order. | Unordered items or a branching process disguised as one sequence | +| `evidence-pair.html` | Keep quotes and attribution together; use only real supplied evidence, remove empty slots. | Invented endorsements or claims without sources | +| `plan-comparison.html` | Align common criteria across real options; adapt labels and actions to the task. Keep labels legible when stacked. | Invented prices or mismatched comparison dimensions | +| `focused-cta.html` | End a section or page with one supported next action and concise context. | A dead action, fake submission, or mandatory closing section without a content reason | + +Source `data-slot` attributes specify the actual copy targets. Trial capacities and allowed variants are indexed in `catalog.md`. Optional slots can be removed; revise geometry accordingly. Repeated fragments need unique IDs and functioning links. Content may increase section height; use content-driven breakpoints, readable measures and intrinsic media proportions. Do not impose a fixed slide canvas. + +Check narrow phone, intermediate and desktop widths, long localized headings, reading order, focus, crops and real interactions after inserting final content/assets. Current evidence covers source/materialization checks only; responsive screenshots, client interaction and real-model generation remain separate acceptance work. diff --git a/apps/server/bundled-templates/core-v1-site-plan-comparison.html b/apps/server/bundled-templates/core-v1-site-plan-comparison.html new file mode 100644 index 000000000..74f669926 --- /dev/null +++ b/apps/server/bundled-templates/core-v1-site-plan-comparison.html @@ -0,0 +1,2 @@ + +Core site plan comparison
diff --git a/apps/server/bundled-templates/core-v1-site-shared-contract.md b/apps/server/bundled-templates/core-v1-site-shared-contract.md new file mode 100644 index 000000000..367e6df89 --- /dev/null +++ b/apps/server/bundled-templates/core-v1-site-shared-contract.md @@ -0,0 +1,9 @@ +# Core Site Shared Contract + +The global library owns structural fragments. The active template owns visual identity, responsive tokens, brand assets and runtime behavior. + +Each file contains one `