pi-apexlang 0.1.0

package/skills/apexlang/references/domains/page-components/regions.md

@@ -0,0 +1,170 @@
+---
+name: regions
+description: Generate Oracle APEX regions using Tier 1 region workflows (interactive report, dashboard, charts, calendars, maps, dynamic actions). Use when Codex must compose region-level APEXlang artifacts with validated SQL, templates, and refresh behaviors.
+---
+
+# Reference Package — Region Workflows
+
+**Parent Entries:** `references/domains/README.md` (domain), `SKILL.md` (router)
+
+This skill orchestrates the Tier 1 region workflows under `skills/` (interactive report, dashboard, charts, dynamic actions, etc.). It mirrors each workflow’s guardrails while coordinating the apexdev internal generate -> review -> fix loop.
+
+---
+
+## Purpose
+- Route region-scoped requests to the correct workflow and template set.
+- Keep region composition, coupled logic, and acceptance gates aligned with the apexdev master contract.
+
+## Covered Workflows
+- `references/domains/page-components/regions/calendar/workflow-calendar-link-targets.md`
+- `references/domains/page-components/regions/interactive-report/workflow-interactive-report.md`
+- `references/domains/page-components/regions/dashboard/workflow-dashboard.md`
+- `references/domains/page-components/regions/chart/workflow-charts.md`
+- `references/domains/business-logic/dynamic-actions/workflow-dynamic-actions.md`
+- `references/domains/business-logic/dynamic-actions/workflow-dynamic-actions-batch.md`
+- `references/domains/page-components/buttons/workflow-button-batch.md`
+- `references/domains/business-logic/computations/workflow-computations-batch.md` (when regions rely on computations)
+- `references/domains/page-components/regions/form/workflow-modal-crud-form.md` (region-level forms embedded on pages)
+- `references/domains/business-logic/processes/workflow-page-processes-batch.md` (invokeApi processes tied to regions)
+- `references/domains/universal-attr-config/workflow-server-side-conditions-batch.md`
+
+Use the component registry (`assets/apex-generation/components.registry.json`) to select the appropriate workflow per region request.
+
+---
+
+## Authoritative Policies
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `references/policies/governance/00-governance.md`
+- `assets/rules-mapping.json`
+- Load minimal domain rules per request from:
+  - `references/policies/memory-bank/10-global/apex.global.md`
+  - `references/policies/memory-bank/20-data/apex.sql.md`
+  - `references/policies/memory-bank/20-data/apex.logic.md`
+  - `references/policies/memory-bank/30-pages/*` relevant to region type
+
+## Operational References
+- Region workflows under `references/domains/page-components/regions/**`.
+- Cross-domain workflows under:
+  - `references/domains/business-logic/**`
+  - `references/domains/page-components/buttons/workflow-button-batch.md`
+  - `references/domains/universal-attr-config/workflow-server-side-conditions-batch.md`
+- Templates from `templates/page-examples/**`, `templates/region-components/**`, and business-logic dynamic-action templates.
+
+## Execution Agents
+- `references/ops/sqlcl-agents/00-connection-gate.md` before agent orchestration.
+- `references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md` for import-ready completion checks.
+- The internal generate/review/fix loop remains under `references/workflows/apex-generation/agents/`.
+- `references/ops/runtime-gates/01-direct-sqlcl-import.md` for online import runs.
+
+---
+
+## Common Required Inputs
+- Region type (IR, chart, dashboard cards, calendar, map, static content, dynamic action archetype)
+- Source table/view(s), primary keys, columns, LOV mappings
+- Page number and anchor region placement
+- Optional calendar create/view link target decisions, including existing-vs-new page choice and any PK/date item mappings
+- For dynamic actions: triggering region/item/button, event, action, refresh targets
+
+### Progressive Prompts
+1. “Are any regions, buttons, or related items guarded by a server-side condition? (Reply ‘none’ to skip.)”
+2. Capture `scope`, `identifier`, catalog `type`, and required attributes per `20-data/apex.logic.md`.
+3. For dynamic actions, ask whether refresh or invokeApi batches are needed; gather page lists for batch modes.
+4. For calendar `createLink`, ask whether to use an existing form page or create a new same-table modal form page.
+5. For calendar `viewEditLink`, ask whether to use an existing report page or create a new report page. If new, ask for report type every time and require a PK item/filter contract.
+
+---
+
+## Rule Loading Sequence
+1. `references/policies/memory-bank/00-guard/ai.guard.md`
+2. `references/policies/governance/00-governance.md`
+3. `assets/rules-mapping.json`
+4. Load minimal extras per region type:
+   - Interactive report → `30-pages/apex.interactive-report.md`, `20-data/apex.sql.md`
+   - Dashboard/cards → `30-pages/apex.dashboard.md`
+   - Charts → `30-pages/apex.chart-page.md`
+   - Calendar → `30-pages/apex.calendar.md`
+   - Modal form region → `30-pages/apex.form.md`, `40-components/apex.items.md`
+   - Dynamic actions → `20-data/apex.logic.md`
+   - Computations → `references/domains/business-logic/computations/workflow-computations-batch.md`
+5. Templates must come from `templates/page-examples/**`, `templates/region-components/**`, and `templates/business-logic/dynamic-actions/**` when applicable.
+
+---
+
+## Agent Pipeline Alignment
+- Start with `references/ops/sqlcl-agents/00-connection-gate.md` (Pre-Agent 0).
+- Use the apexdev internal generate -> review -> fix loop to produce region artifacts:
+  - working changes stay in a transient temp workspace outside the repo
+  - internal review enforces SQL validation, UT classes, SSC catalog, process policy split, and confidence `>= 0.95`
+  - final publish happens only after the resolved live runtime action succeeds when a live roundtrip is requested
+- For import-ready runs, execute `references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md`.
+- After runtime gate pass, call `references/ops/runtime-gates/01-direct-sqlcl-import.md` automatically.
+
+---
+
+## Guardrails
+- Validate SQL via `20-data/apex.sql.md`; no inline `select` inside `plsqlExpression`.
+- Enforce invokeApi-default for page processes tied to regions, allow the thin-wrapper exception only for page-coupled loaders or branch-gated flows, and enforce executeCode-only for appProcess.
+- Dynamic actions should use declarative templates (e.g., `dynamic-action-refresh-report.apx`); avoid inline JS beyond approved locations.
+- Report regions that launch modal pages must include an `apexafterclosedialog` dynamic action that refreshes the originating report region.
+- Map regions should follow the attached canonical structure from the map family: `layout.slot: body` where the page pattern requires it, `initialPositionAndZoom`, layer `source { ... }`, and `columnMapping.geometryColumnDataType`.
+- For standard non-login pages, region `layout.slot` should default to `body`. Use `contentBody` only when the active login or modal page-template contract explicitly requires it.
+- Map-layer source modes are:
+  - `source { tableName: ... }` for the preferred simple path
+  - `source { type: sqlQuery sqlQuery: ... }` for new SQL-backed layers
+  - `source { type: functionBody plsqlFunctionBody: ... }` for advanced fallback cases
+- Legacy bare `source { sqlQuery: ... }` remains accepted for existing artifacts during transition, but new SQL-backed map layers should emit `source.type: sqlQuery`.
+- Charts/calendars must reference existing template files; no new chart types invented.
+- Chart routing must use the checked-in chart family entrypoints directly:
+  - `templates/region-components/chart/chart._index.md`
+  - `templates/region-components/chart/chart._common.md`
+  - `templates/region-components/chart/chart._series._common.md`
+  - `templates/region-components/chart/chart._axis._common.md`
+  - plus exactly one chart-type qualifier file such as `chart.line.md`, `chart.bar.md`, or `chart.area.md`
+- For compiler-backed chart lookup, start with the dotted aliases:
+  - `--component chart.series`
+  - `--component chart.axis`
+  - `--component chart.series --group columnMapping`
+- Do not query chart `series` or `axis` with `--parent region`; in this runtime the compiler resolves those child contracts under chart `attributes`, so the `parent region` path is a dead end.
+- If compiler-backed prop lookup is uncertain for a chart subtype, do not bounce through directory listings or repeated token guesses. Use the chart router and qualifier files above as the canonical drafting path.
+- Calendar regions must follow compiler-truth-backed calendar guidance first, normalize the event-label mapping to `displayColumn`, require `settings.pkColumn` from the source table primary key column, keep `endDateColumn` optional even when drag/drop is enabled, restrict `settings.additionalCalendarViews` to `list` and `navigation`, preserve combined UT option values exactly as listed in the template or valid-value catalog, and treat calendar create/edit link targets as user-provided intent rather than something the agent can infer. Use `assets/component-attributes.json` only as fallback/internal validator context.
+- Calendar `createLink` and `viewEditLink` requests must follow the explicit clarification workflow for existing-vs-new target pages. New `viewEditLink` report pages must have an explicit report type plus a PK item/filter contract.
+- Batch workflows require explicit page lists; stop if missing.
+- Record Missing Inputs for absent PKs, LOVs, or SSC attributes.
+
+---
+
+## Outputs & Acceptance Gates
+- Regions publish into the resolved page artifact under `applications/app_###/pages/` unless the calling master passes a resolved application path.
+- Interactive report completion checks: validated SQL, button/item SSC compliance, optional edit form link consistent with region.
+- Dashboard/cards: correct template usage, KPIs respect UT classes.
+- Charts: measure/dimension validated, chart dataset defined via templates.
+- Dynamic actions: refresh or invokeApi actions wired with proper selectors; guard DML by button/process.
+- Batch outputs (buttons/DA/processes) must include change logs summarizing affected pages/components.
+
+---
+
+## Completion Checklist
+1. Working region changes stay in the transient temp workspace until review passes.
+2. Internal review captures PASS/CONFIDENCE, SQL validation status, and SSC compliance notes.
+3. Final region artifacts are published only after required gates pass.
+4. Runtime gate executes for import-ready runs.
+5. After runtime gate pass, the import gate executes automatically.
+
+---
+
+## Examples
+These are `illustrative_prompt` examples. Replace any `{{...}}` variables with verified identifiers before use.
+
+- “Create an interactive report on {{source.table}} with modal form for edits and dynamic action to refresh after submit.”
+- “Add dashboard cards for Sales KPIs using existing page 10.”
+- “Apply dynamic action batch to refresh regions on pages 12, 14, 20 when timer fires.”
+
+---
+
+Use this skill whenever region-level composition or updates are requested within the apexdev orchestration.
+
+## Parallel Skill Contract
+- Emit `claims` describing region-level outputs and targeted pages/components.
+- Emit `required_inputs` and `assumptions` for unresolved identifiers.
+- Emit `source_paths` for every workflow/template path consumed.
+- If another parallel skill disagrees on identifiers or dependencies, stop and record `Missing Inputs` instead of guessing.

package/skills/apexlang/references/domains/page-components/screenshot-to-layout/component-mapping.md

@@ -0,0 +1,119 @@
+# Screenshot Pattern to APEX Component Mapping
+
+Map screenshot regions to the narrowest safe native APEX primitive region only after the full layout tree has been derived. This reference chooses region types; it must not drive or alter the already-established region structure.
+
+## Mapping Contract
+- Treat the layout tree as fixed input.
+- Treat the lane tree and any outer or nested structural placeholder regions as fixed input before mapping visible regions.
+- Component mapping may choose only the region type and the nearest native APEX primitive behavior.
+- Component mapping must not collapse, merge, reorder, resize, or omit regions that were already derived from the screenshot.
+- Component mapping must not change the top-level row plan or replace a same-row sibling relationship with a vertical stack.
+- Component mapping must not bypass established outer or nested lane placeholders once the structural scaffold has been chosen.
+- Native primitive regions are the required first-choice targets, including Metric Card template components for KPI strips, cards, interactive reports, classic reports, charts, lists, form regions, page items, and buttons.
+- When mapping confidence is low, preserve the same region position and size intent and use a `staticContent` region instead.
+- When one preserved region contains several nearby aggregate metrics, map it to one grouped `themeTemplateComponent/metricCard` region with one normalized SQL query that returns multiple rows as the default choice.
+- When one preserved region contains several nearby entity, media, or navigation cards, map it to one grouped native `cards` region with one SQL query that returns multiple rows as the default choice.
+- Do not create one region per metric, one cards region per entity card, or one staticContent region per metric unless the screenshot clearly shows distinct containers separated into different regions.
+
+## Common Mappings
+- Page title + top-right actions:
+  - Use the page title area plus buttons associated with the breadcrumb or title region when supported by the target page pattern.
+- Search/filter strip with labeled inputs:
+  - Use a form-style region with page items.
+- Tabular data listing:
+  - Prefer interactive report.
+  - Use interactive grid only when the screenshot clearly suggests inline editing.
+- KPI tiles or summary counts:
+  - First try one grouped `themeTemplateComponent/metricCard` region backed by one normalized SQL query when the metrics sit close together in the same region.
+  - Fall back to one region per metric only when the screenshot clearly gives each metric its own container.
+- Detailed record editor:
+  - Use a form region.
+- Side filter panel + main content:
+  - Use an asymmetric sidebar/main split.
+- Chart areas:
+  - Use chart regions only when the chart type is clear enough from the screenshot.
+- Utility panels made of links or tasks:
+  - Prefer a shared list plus a native `list` region.
+  - Create shared list entries from the visible labels before falling back to `staticContent`.
+- Search or filter form areas:
+  - Prefer real page items for visible controls and real buttons for visible actions.
+  - Keep related controls together in one shared form or structural layout container.
+- Hero + feature + form pages:
+  - Preserve the visible row order: hero copy, feature cards, form controls, then action row.
+- Mixed utility panel with unclear internal widget type:
+  - Use a placeholder static region.
+
+## Placeholder Static Region Rules
+- Use a placeholder static region when:
+  - the section is visibly important
+  - the label or purpose is partially clear
+  - the exact APEX component type is uncertain
+- Preserve the region position, grouping, nesting, and size intent from the layout tree.
+- Use `staticContent`.
+- Include concise descriptive placeholder text such as:
+  - `Placeholder for shipment status timeline.`
+  - `Placeholder for custom operations heatmap.`
+  - `Placeholder for exception review workspace.`
+- Label the region clearly, for example:
+  - `Activity Timeline Placeholder`
+  - `Custom Metrics Panel Placeholder`
+  - `Map or Visual Panel Placeholder`
+- Keep the placeholder structural and descriptive.
+- Do not embed HTML, custom markup, fake widget code, or decorative markup that tries to imitate the screenshot.
+- Do not use HTML fallback for mapped regions either.
+- Do not use placeholder prose to simulate card badges, report rows, chart bars, form layouts, or other primitive-region UI.
+
+## Confidence Heuristics
+- High confidence:
+  - obvious forms, reports, cards, buttons, tabs, or charts
+- Medium confidence:
+  - a structured panel whose purpose is visible but whose exact behavior is unclear
+  - choose the closest safe native primitive region
+- Low confidence:
+  - bespoke widget, unreadable text, or decorative composite control
+  - emit a placeholder static region without changing the region layout
+
+## Layout Heuristics
+- Top-level page rows:
+  - preserve the screenshot's row count and row membership before component choice
+  - do not wrap separate page rows in a synthetic parent unless the screenshot shows one framed parent container
+- Lane tree first:
+  - determine the page-wide outer lanes or columns before assigning component families
+  - determine whether any parent lane owns recurring child lanes or sub-columns
+  - keep outer and inner structural placeholders in place once they are chosen
+- Balanced sibling panels:
+  - use implicit equal-width flow
+- Uneven sidebar/main or 3-zone composition:
+  - use explicit `column` and `columnSpan`
+  - keep those panels as same-row siblings rather than stacked full-width regions
+- Multi-column outer scaffolds:
+  - support one, two, three, or more outer structural lanes when the screenshot alignment depends on stable page-wide columns
+  - `LEFT`, `CENTER`, `RIGHT`, `MAIN`, `RAIL`, `TOP_LEFT`, and similar names are examples only, not a fixed catalog
+- Anchored sidebar stacks:
+  - keep each framed sidebar panel as its own top-level BODY region
+  - anchor repeated sidebar peers to the same right-side columns with explicit placement when needed
+  - do not hide those peers inside a synthetic sidebar wrapper
+  - treat this as one special case of the broader lane-tree model, not the default shape for every multi-column page
+- Constrained lower workspace rows:
+  - when two or more panels sit below the main workspace and together match the workspace width, preserve that shared width budget
+  - if needed, use a minimal invisible parent container for the constrained row, then place the child panels inside it with implicit equal-width flow
+- Stacked lane containers:
+  - when multiple visible regions belong to the same vertical lane, allow a minimal outer structural region for that lane
+  - outer lane regions must use `@/blank-with-attributes`
+  - outer lane regions are structural only and must not add visible chrome
+  - the pattern is not limited to two columns; use as many structural placeholder regions as needed for the screenshot topology
+- Nested child-lane containers:
+  - when a parent lane contains recurring inner columns, allow nested structural placeholder regions for those child lanes
+  - nested child-lane regions must also use `@/blank-with-attributes`
+  - nested child-lane regions are structural only and must not add visible chrome
+  - prefer nested structural placeholders when they preserve recurring alignment more cleanly than repeated explicit placement
+- Dense page with clear visual sections:
+  - preserve the section order and region boundaries even if some areas must become placeholders
+- Metric or KPI strips:
+  - treat one visually grouped strip as one region first, then use one `themeTemplateComponent/metricCard` region with one normalized source row per metric
+  - do not remap a grouped strip into one static region per metric when Metric Card is still a safe native mapping
+- Entity, media, or navigation card groups:
+  - treat one visually grouped block as one region first, then use one native `cards` region with multiple rows inside it
+- Actions or links panels:
+  - if the content reads as a vertical list of navigation or task options, model it as a shared list and render it with a `list` region
+  - reserve `staticContent` for utility panels whose internal widget type is still unclear after inspection

package/skills/apexlang/references/domains/page-components/screenshot-to-layout/workflow.md

@@ -0,0 +1,95 @@
+# Screenshot-to-Layout Workflow
+
+Use this workflow to turn one screenshot into one APEXlang page draft by deriving the exact region layout first and assigning native APEX primitive region types second.
+
+## Inputs
+- Screenshot file at `image_path`
+- Existing target app at `app_path`
+- `page_id`
+- `page_title` or slug
+- Optional notes
+
+Before drafting the page, inspect the target app's shared navigation and breadcrumb files so the new page can be integrated using the same shared-component containers and concrete target format already present in that app.
+
+## Workflow
+1. Inspect the screenshot and identify:
+   - page title area
+   - major regions
+   - actions
+   - filters or forms
+   - reports, cards, charts, and detail areas
+2. Write a top-level BODY row plan before mapping components:
+   - which regions belong to row 1
+   - which regions belong to row 2
+   - which regions belong to row 3
+   - where the screenshot shows an asymmetric split such as main area plus right rail
+3. Run an explicit lane-tree pass before choosing visible region types:
+   - determine the page-wide outer columns or lane groups first
+   - determine whether any parent lane contains nested child columns that need their own structural placeholders
+   - create outer and inner placeholder regions before planning visible descendants
+   - preserve alignment through shared structural parents rather than rebuilding the same columns row-by-row
+4. Convert the screenshot into a fully nested layout tree before choosing any APEX component:
+   - top-level rows
+   - outer lane membership for each visible region
+   - nested child-lane membership where a parent lane owns inner columns
+   - sibling groups within each row or lane scope
+   - nested content blocks when visibly framed together
+   - width/span intent for each region
+5. Choose the row recipe for each scope so the emitted APEX page preserves the derived layout:
+   - `stack`
+   - `two-up-equal`
+   - `three-up-equal`
+   - explicit asymmetric split only when visually obvious
+   - anchored sidebar stack: repeated top-level BODY peers fixed to the same right-side columns
+   - constrained subordinate row: a minimal invisible container that preserves the main-workspace width for a lower two-up row
+   - stacked lane container: a minimal invisible structural region that owns one vertical lane of child regions
+   - 3-column dashboards may require three outer structural placeholders before any visible regions are placed
+   - a main workspace plus right rail may also require nested child placeholders inside the main workspace for lower two-up or three-up rows
+   - center-focused layouts may still use left and right support lanes when the screenshot alignment depends on them
+   - multi-row pages may reuse the same outer lanes while only some parent lanes contain nested child columns
+6. Freeze the structural scaffold and region layout tree once the structure is clear.
+7. Map each preserved region to the nearest native APEX primitive region family first.
+8. When a preserved region is a cluster of nearby aggregate metrics, emit one grouped `themeTemplateComponent/metricCard` region with one normalized SQL query returning multiple rows as the first mapping choice.
+9. When a preserved region is a cluster of nearby entity, media, or navigation cards, emit one grouped native `cards` region with one SQL query returning multiple rows as the first mapping choice.
+10. Split that cluster into separate peer regions only when the screenshot clearly shows distinct containers, headings, or spacing that make each metric or card its own region.
+11. When a preserved region is clearly a vertical task or navigation panel, create a shared list with the visible entries and emit a `list` region that references it.
+12. When a preserved region is clearly a search or filter form, emit real page items for the visible controls and real buttons for the visible actions inside one shared form/layout container.
+13. If no primitive region matches safely, keep it in the same layout position as a `staticContent` region with short descriptive placeholder text only.
+14. Do not use `source.htmlCode`, custom markup, or decorative static content to mimic cards, reports, charts, forms, or other screenshot regions.
+15. If the target app already uses shared navigation or breadcrumbs, add one navigation-menu entry and one breadcrumb entry for the new page by reusing the existing shared-component ids, entry containers, and target format already present in the app.
+16. Emit the page draft and any required shared-component updates so the new page matches the screenshot layout and integrates cleanly with the target app.
+
+## Layout Priorities
+1. Preserve exact region structure.
+2. Preserve exact ordering, grouping, and nesting.
+3. Preserve approximate component choice without changing the layout tree.
+4. Treat styling as last.
+
+## Clarification Gate
+- Ask one short follow-up only when a blocking ambiguity changes:
+  - the destination page identity
+  - a major region type
+  - a clearly visible label or action that appears central to the page
+- If the page is still ambiguous after that round, stop with `Missing Inputs`.
+
+## Guardrails
+- Do not use HTML code, HTML regions, `source.htmlCode`, or HTML-like static markup to mimic screenshot fragments.
+- Do not use `staticContent` as a visual recreation tool; use it only as a descriptive placeholder shell when no native APEX primitive region is a safe match.
+- Do not use fake widget markup or decorative text blocks to imitate cards, reports, charts, form controls, or other primitive regions.
+- Do not invent business logic or SQL.
+- Do not collapse multiple top-level screenshot rows into one generic page stack or one oversized synthetic wrapper region.
+- Do not turn a clear sidebar/main composition into sequential full-width regions.
+- Do not implement an anchored right rail as one top-level sidebar wrapper with nested child regions when the screenshot shows separate framed sidebar panels.
+- Do not let a lower two-up summary row stretch to the full page width when the screenshot keeps it within the main workspace footprint.
+- When several visible regions belong to the same vertical lane, prefer one invisible outer lane region instead of repeated spacing hacks or ad hoc wrappers.
+- When a parent lane contains recurring inner columns, prefer nested structural placeholder regions instead of re-solving those child columns independently in each row.
+- Do not assume the layout can only be expressed with `LEFT` and `RIGHT`; add as many structural placeholder regions as the screenshot topology requires.
+- Use structural placeholder regions to preserve stable outer and inner column boundaries, not as an afterthought once component mapping has already started.
+- Do not silently drop, merge, or reorder visible sections after the layout tree is derived.
+- Do not split one visually grouped KPI strip into multiple regions or one static region per metric unless the screenshot clearly shows separate region containers.
+- For KPI strips, grouped `themeTemplateComponent/metricCard` is the expected default mapping. Use native Cards only when the user explicitly asks for Cards/native cards or when the visible content is an entity/media/navigation card grid.
+- Do not render obvious `Actions`, `Links`, `Resources`, or `Quick Links` panels as static text when native shared lists plus list regions are a safe mapping.
+- Do not render obvious form controls or action buttons as static text when real page items and real buttons are a safe native mapping.
+- Placeholder static regions must include short descriptive placeholder text only in the region body.
+- Do not route into import or runtime workflows from this package by default.
+- Do not create a new page draft without also updating the app's shared navigation or breadcrumb definitions when those patterns already exist in the target app.

package/skills/apexlang/references/domains/page-components/screenshot-to-layout.md

@@ -0,0 +1,204 @@
+---
+name: screenshot-to-layout
+description: Turn a desktop enterprise UI screenshot or mockup into an Oracle APEX page draft by deriving the exact region layout first. Use when Codex must inspect a local image file, match region topology, ordering, nesting, and width intent as closely as possible, then map each preserved region to native APEX primitive regions only, with plain-text placeholder `staticContent` only when no primitive region is a safe match.
+---
+
+# Reference Package — Screenshot to Layout
+
+**Parent Entries:** `references/domains/README.md` (domain), `SKILL.md` (router)
+
+This package converts a screenshot-driven page concept into one APEXlang page draft staged under a transient app copy. Its primary output is an exact region layout plan: derive the full region structure first, preserve that structure in the emitted page, and only then choose the nearest native APEX primitive region for each region, such as cards, reports, charts, lists, form regions, page items, and buttons. If a region cannot be mapped confidently to a primitive region, preserve it as a `staticContent` region with brief placeholder text describing what belongs there.
+
+## Use When
+- The user has a local screenshot, wireframe, or mockup for a desktop enterprise page.
+- The goal is to create one APEXlang page draft whose region layout, grouping, nesting, and reading order match the screenshot as closely as possible.
+- The target app already exists under `applications/<target-app>/`, but working changes for this workflow must stay in a transient temp workspace outside the repo until the run passes review and runtime gates.
+
+## Do Not Use When
+- The request is general APEX page generation without an image; use `SKILL.md`.
+- The request is specification work without page-generation intent.
+- The screenshot is primarily mobile, marketing, or highly bespoke brochure-style design.
+- The user wants pixel-perfect theming, direct runtime import, or markup-based recreation of screenshot fragments.
+
+## Required Inputs
+- `image_path`
+- `app_path`
+- `page_id`
+- `page_title` or page slug
+
+## Optional Inputs
+- Notes for unreadable labels, intended actions, data-source hints, component preferences, or business context.
+
+## Output Contract
+- Generate exactly one APEXlang page update in the transient temp workspace, then publish it to `applications/<target-app>/pages/p<PageId>-<slug>.apx` only after the run passes review and any requested runtime gates.
+- When the target app already uses shared navigation and breadcrumbs, update the app's navigation menu list and breadcrumb shared components using the target app's existing identifiers and entry format as concrete integration facts only.
+- Derive the complete region layout tree before choosing component types.
+- Determine the page's structural lane tree before detailed region mapping:
+  - top-level rows
+  - outer lanes or columns
+  - nested child lanes inside any parent lane that reuses inner columns
+- Derive and preserve the screenshot's top-level page row plan before introducing nested regions or choosing components.
+- Keep region topology, order, nesting, and width/span intent intact while mapping regions to native APEX primitive regions.
+- Primitive-first mapping is mandatory: try cards, reports, charts, lists, form regions, page items, buttons, and other native APEX primitives before considering `staticContent`.
+- If a region does not map confidently to a primitive region, preserve it as a `staticContent` region with brief placeholder text describing the expected content or behavior.
+- Do not perform the live APEXlang check, SQLcl roundtrip, or import by default.
+- Do not generate non-page artifacts from this package.
+
+## Authoritative Reuse
+- Parent APEX generation context: `SKILL.md`
+- Page-composition domain context: `references/domains/README.md`
+- Layout rules: `references/policies/memory-bank/30-pages/apex.layout.md`
+- Template defaults: `references/policies/memory-bank/40-components/apex.templates.md`
+- Use existing APEXlang templates under `templates/`
+
+## Router Contract
+- Router: true
+- Kind: one-message
+- TargetWorkflow: `references/domains/page-components/screenshot-to-layout.md`
+- Match keywords:
+  - `screenshot`
+  - `mockup`
+  - `wireframe`
+  - `image to apex`
+  - `screenshot to layout`
+  - `render page from image`
+- Defaults:
+  - `image_path: ""`
+  - `app_path: ""`
+  - `page_id: ""`
+  - `page_title: ""`
+  - `notes: ""`
+  - `prompt_normalization: enabled`
+  - `clarification_rounds_max: 1`
+  - `clarification_style: simple_english`
+  - `ambiguity_policy: ask_then_stop`
+
+## Operating Rules
+- Accept free-form prompts by default and normalize them before determining whether required inputs are present.
+- Load only the minimum screenshot-specific guidance first:
+  - `references/domains/page-components/screenshot-to-layout.md`
+  - `references/domains/page-components/screenshot-to-layout/workflow.md`
+  - `references/domains/page-components/screenshot-to-layout/component-mapping.md`
+- Load `SKILL.md` only as the parent generation context for the emitted page format.
+- Load `references/policies/memory-bank/30-pages/apex.layout.md` and `references/policies/memory-bank/40-components/apex.templates.md` before assigning any region types.
+- Inspect the target app's existing shared navigation and breadcrumb files before drafting the page so any new page entry can reuse the app's concrete shared-component identifiers, entry containers, and target references without using the app as a pattern source.
+- For page-scoped screenshot generation, use `templates/page-examples/**` as the page-pattern source before consulting narrower region families.
+- Commit to a structure-first planning pass before component mapping:
+  - top-level BODY row plan
+  - page-wide outer lane or column structure
+  - nested child lane structure inside any parent lane that reuses inner columns
+  - frozen structural scaffold before visible component mapping
+- Derive the region layout tree first: top-level rows, sibling membership, outer lane ordering, nested lane ownership, and width intent.
+- Treat structural placeholder regions as the default alignment tool whenever stable outer or inner columns repeat across rows or within a parent lane.
+- Keep screenshot rows at the same hierarchy level whenever the screenshot shows them as peer page rows; do not wrap dissimilar rows in a synthetic container just because generation becomes easier.
+- When a screenshot depends on stable page-wide columns or lanes, preserve those columns first with shared structural placeholder regions instead of rebuilding the same alignment row-by-row.
+- When the screenshot shows a dominant left workspace with a stacked right rail of individually framed panels, keep those right-rail panels as repeated top-level BODY peers anchored to the same right-side columns.
+- When a lower summary row visually belongs under that dominant left workspace, keep its combined width constrained to the same left-workspace footprint instead of letting it expand underneath the right rail.
+- When multiple visible regions stack within the same column or lane, prefer one minimal outer layout region for that lane and place the visible regions inside it as children.
+- Support one, two, three, or more outer lanes whenever the screenshot topology requires them.
+- Support nested structural child lanes inside parent lanes whenever a parent lane contains its own repeated inner columns.
+- Do not let component substitution collapse, merge, reorder, resize, or omit screenshot regions once the layout tree is established.
+- Treat component mapping as a second-phase decision that chooses a region type only after the layout is fixed.
+- Treat component mapping as a primitive-first decision: use native APEX primitive regions only to represent screenshot regions whenever a safe match exists.
+- When several nearby aggregate metrics clearly belong to one visual KPI strip, treat that strip as one preserved region and map it to a single `themeTemplateComponent/metricCard` region backed by one normalized SQL query unless the user explicitly specifies native Cards.
+- When several nearby entity, media, or navigation cards clearly belong to one grouped block, treat that block as one preserved region and map it to a single native `cards` region backed by one SQL query before considering any one-region-per-card fallback.
+- Do not emit one region per metric for KPI strips unless the screenshot clearly shows separate region containers with meaningful spacing, framing, or headings between metrics.
+- When a utility panel is primarily a vertical set of navigational or task links labeled with headings such as `Actions`, `Links`, `Resources`, or `Quick Links`, first map it to a shared list plus a `list` region rather than a `staticContent` region.
+- When a screenshot is primarily a search or filter form, prefer real page items and real buttons over `staticContent` placeholders for the visible controls and actions.
+- When several controls clearly belong to one cohesive form block, keep them inside one shared form or structural layout container instead of fragmenting them into unrelated peer regions.
+- When a page reads as centered hero + feature strip + form + action row, preserve that row order explicitly.
+- Use `staticContent` only as a plain-text placeholder shell when no native APEX primitive region is a safe fit; do not use it to simulate cards, reports, charts, forms, or other primitives.
+- Ask at most one short clarification round when a blocking ambiguity materially changes the destination page or a major region mapping.
+- If ambiguity remains after that round, stop with `Missing Inputs`.
+- When creating a new page draft, do not leave it orphaned from shared navigation. Add the matching navigation-menu entry and breadcrumb entry unless the target app clearly does not use those shared components.
+- Keep this package focused on structure-first page composition. Resolve template, grid, lane, and template-option decisions through `references/policies/memory-bank/40-components/apex.templates.md`; do not broaden the workflow into non-structural skinning.
+
+## Safety Directive
+- Err on the side of caution when the screenshot is ambiguous.
+- Region layout accuracy outranks component fidelity and styling fidelity.
+- Prefer native APEX primitive regions over custom recreation, but only after the screenshot region layout has been preserved.
+- Page-level layout fidelity outranks local component convenience. Do not flatten a multi-row screenshot into a generic vertical stack of regions.
+- If a section is clearly present but the exact component type is uncertain, keep the region in place as a `staticContent` region and add brief placeholder text describing the intended content or behavior.
+- Do not use `source.htmlCode`, HTML regions, HTML-like static markup, or decorative markup to imitate screenshot widgets or region chrome.
+- Do not use `staticContent` to visually recreate cards, reports, charts, forms, timelines, or composite widgets; use native APEX primitive regions for those whenever a safe mapping exists.
+- Prefer under-specifying behavior over inventing SQL, LOVs, validations, processes, unsupported controls, or fake interactivity.
+- Never drop a visible screenshot region because it lacks a confident APEX component mapping.
+- Do not over-fragment nearby metrics into multiple regions or multiple static regions when the screenshot shows them as one grouped KPI strip.
+- For KPI strips, a grouped Metric Card region is the default mapping, not an optional enhancement. Use native Cards only when the user explicitly asks for Cards/native cards or when the visible content is an entity/media/navigation card grid.
+- Do not leave obvious navigational link panels as raw static text when a native shared list plus list region is a plausible mapping.
+- Do not invent synthetic parent regions for whole page sections unless the screenshot clearly shows a framed parent container around those child regions.
+- Do not solve an anchored side rail as `main region + sidebar wrapper with nested children` when the screenshot shows individually framed right-rail cards.
+- Do not let subordinate lower rows spill to full-page width when the screenshot shows them constrained under the main workspace beside an empty or shorter right rail.
+- A minimal invisible layout container is allowed only when it is needed to preserve a constrained sub-row width such as “two panels inside the main 9-column workspace,” and the screenshot does not require that container to render visible chrome.
+- Outer and inner lane regions are placeholders only: always use `appearance.template: @/blank-with-attributes`, do not rely on them to render visible UI chrome, and keep their names structural rather than user-facing.
+- Placeholder-region naming is intentionally flexible. `LEFT`, `CENTER`, `RIGHT`, `MAIN`, `RAIL`, `TOP_LEFT`, `BOTTOM_RIGHT`, and similar names are examples only; use as many structural placeholder regions as the screenshot topology requires.
+- Structural placeholder regions should be preferred whenever they preserve recurring alignment more cleanly than repeated explicit placement, but do not introduce wrappers that do not correspond to real alignment needs in the screenshot.
+- Do not leave obvious form controls or action buttons as static prose when the screenshot clearly indicates interactive fields and actions.
+
+## Generation Algorithm
+1. Read the screenshot and identify every visible region, grouping, heading, control cluster, action area, and reading-order transition.
+2. Write the top-level BODY row plan explicitly in working memory before choosing region types:
+   - row 1 siblings
+   - row 2 siblings
+   - row 3 siblings
+   - any asymmetric split ratios
+3. Determine the page's structural lane tree before mapping visible regions:
+   - outer lanes or columns that persist across the page
+   - any parent lane that owns nested child lanes or sub-columns
+   - which visible regions belong directly to an outer lane versus a nested child lane
+   - where shared structural placeholder regions are required to preserve stable alignment
+4. Freeze the structural scaffold before choosing region types:
+   - outer lane placeholders first
+   - nested child lane placeholders second
+   - visible descendant regions only after the lane tree is fixed
+5. Choose row recipes from `references/policies/memory-bank/30-pages/apex.layout.md` to preserve the derived layout as closely as possible.
+   - keep equal-width rows implicit
+   - keep asymmetric rows as same-row siblings with explicit spans only where needed
+   - for anchored side rails, repeat explicit right-side placement on each top-level peer region instead of nesting them in a wrapper
+   - if a lower summary row must stay within the main workspace width, constrain that row to the same width budget before placing its child panels
+   - when a whole vertical lane contains several stacked regions, use one outer structural placeholder region for that lane
+   - when a parent lane contains recurring inner columns, use nested structural placeholder regions for those child lanes
+   - keep lower summary rows separate from the main workspace row when the screenshot does
+6. Map each preserved visible region to the closest native APEX primitive region using `references/domains/page-components/screenshot-to-layout/component-mapping.md`.
+7. When a preserved region contains several nearby aggregate metrics that read as one grouped KPI strip, emit one `themeTemplateComponent/metricCard` region with one normalized SQL query returning multiple rows as the default outcome.
+8. When a preserved region contains several nearby entity, media, or navigation cards, emit one native `cards` region with one SQL query returning multiple rows as the default outcome.
+9. Only split a grouped KPI strip or card block into multiple peer regions when the screenshot clearly indicates each metric or card is its own region through separate framing, spacing, or headings.
+10. When a preserved region is clearly a task or navigation link panel, create a shared list with the visible entries and map the region to a native `list` region before considering `staticContent`.
+11. When a preserved region is clearly a search or filter form, emit real page items for the visible controls and real buttons for the visible actions before considering `staticContent`.
+12. If no native APEX primitive region maps confidently, keep the region in the same place and emit it as `staticContent` with brief placeholder text such as "Placeholder for shipment status timeline."
+13. Do not use HTML, custom markup, or styled static content to mimic the original screenshot region when falling back to `staticContent`.
+14. Generate visible labels and buttons only after the structural scaffold and visible region placement are settled.
+15. Inspect the target app's shared breadcrumb and navigation menu definitions and add one entry for the new page by reusing the existing shared-component containers and concrete target format already present in that app.
+16. Do not invent SQL, item validations, process logic, dynamic actions, or shared-component dependencies unless the user supplied them in notes, except for the shared navigation and breadcrumb entries required to integrate the new page into an app that already uses them.
+
+## Acceptance Checklist
+- Exactly one page draft path is resolved.
+- When the target app uses shared navigation or breadcrumbs, the draft includes matching updates to those shared components so the page is reachable and integrated without using the app as a pattern corpus.
+- The page preserves the screenshot's region topology, ordering, grouping, nesting, and width intent as closely as possible within native APEX layout rules.
+- The page preserves the screenshot's top-level row count and sibling grouping instead of collapsing multiple rows into a simpler stack.
+- Lane-tree extraction happens before component mapping.
+- Equal-width rows use implicit flow; explicit coordinates appear only for intentionally asymmetric layouts.
+- Sidebar/main layouts remain same-row siblings with asymmetric spans when the screenshot shows a side rail.
+- Anchored right-rail panels remain top-level BODY peers rather than children of a synthetic sidebar wrapper.
+- Lower summary rows that sit under the main workspace stay within that same width budget instead of stretching beneath the right rail.
+- Outer lane regions used to group stacked columns are structural placeholders only and always use `@/blank-with-attributes`.
+- Nested child lane regions use the same structural-placeholder contract when a parent lane contains recurring inner columns.
+- The pattern supports more than just `LEFT` and `RIGHT`; use as many structural placeholder regions as the screenshot layout needs.
+- Stable outer columns and stable inner child columns are preserved with shared structural parents rather than recomputed row by row.
+- Nearby aggregate metrics that visually belong together are emitted as one Metric Card region with one normalized SQL source unless the screenshot clearly separates them into distinct regions.
+- A screenshot metric strip must not degrade into one staticContent region per metric when a grouped Metric Card region is a plausible native APEX mapping.
+- Visible utility panels made of actionable or navigational links prefer shared lists plus `list` regions over `staticContent`.
+- Screenshot-derived search or filter pages use real page items and real buttons for obvious controls and actions.
+- Centered hero + feature strip + form + action row compositions preserve that row order explicitly.
+- Dissimilar sections that appear as separate screenshot rows are not hidden inside one synthetic parent region unless the screenshot shows a shared parent frame.
+- Unmappable or uncertain regions remain in place as `staticContent` regions with brief descriptive placeholder text only.
+- No screenshot region is recreated with HTML, HTML-like markup, or decorative static markup.
+- No HTML fallback is used.
+- No screenshot regions are dropped, merged away, or reordered because of component limitations.
+- The package asks at most one clarification round.
+- The run stops before validate/import/runtime work unless the user explicitly switches workflows.
+
+## Example Triggers
+- "Use `screenshot-to-layout` to turn `/tmp/customer-search.png` into page 12 in `applications/layout`."
+- "Create an APEX page from this wireframe screenshot, matching the region layout precisely before choosing components."
+- "Render this mockup into an APEXlang page draft, preserving every screenshot region and using descriptive static regions where the widget type is unclear."