sdtk-ops-kit 0.2.9 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SDTK
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  ## Package
6
6
 
7
7
  - Package: `sdtk-ops-kit`
8
- - Version in this source snapshot: `0.2.9`
8
+ - Version in this source snapshot: `0.3.0`
9
9
  - CLI: `sdtk-ops`
10
10
  - Latest published version lookup: `npm view sdtk-ops-kit version`
11
11
 
@@ -159,6 +159,7 @@ Canonical journeys:
159
159
  - incident: `ops-incident -> ops-debug -> ops-deploy` when rollback or corrective rollout is needed, then `ops-monitor -> ops-verify`
160
160
  - monitoring: `ops-plan -> ops-monitor -> ops-verify`
161
161
  - backup or recovery: `ops-plan -> ops-backup -> ops-verify`
162
+ - Framer template deploy: `ops-plan -> ops-framer-deploy -> ops-verify`
162
163
 
163
164
  Always close work with `ops-verify`.
164
165
 
@@ -1,12 +1,12 @@
1
1
  {
2
- "version": "0.2.9",
3
- "sourceCommit": "12c007b7b4588c7cf1bf13a34ebee83bb9d2e40b",
4
- "fileCount": 36,
2
+ "version": "0.3.0",
3
+ "sourceCommit": "6896f2f26dfc5aee3f71751e869b80608e34ecb7",
4
+ "fileCount": 44,
5
5
  "files": [
6
6
  {
7
7
  "path": "toolkit/AGENTS.md",
8
- "sha256": "5c76955ecabfae64759c11a3ee0fa777b1e0c0f78bdd177ae8f04340cd572e4b",
9
- "size": 16469
8
+ "sha256": "77d09c309061991343ef7ae42181afb7b8f9684c74a3f3a10166c93dbcec6508",
9
+ "size": 16553
10
10
  },
11
11
  {
12
12
  "path": "toolkit/install.ps1",
@@ -15,22 +15,22 @@
15
15
  },
16
16
  {
17
17
  "path": "toolkit/scripts/install-claude-skills.ps1",
18
- "sha256": "5eae77f4d14b81d56c3c109f563fefafd1967d85093ff1b192293fe438aeabe5",
18
+ "sha256": "53fddfb0424676929f72d844faa319f2e4eba9252f1c2c31fd8780c9a61f224a",
19
19
  "size": 2474
20
20
  },
21
21
  {
22
22
  "path": "toolkit/scripts/install-codex-skills.ps1",
23
- "sha256": "68eb662bc9b8906882d32f6cd1247238f6ae663137a489f18054a75724cd1e81",
23
+ "sha256": "a3451bd0978790d2bca9eecce1f2ab79e9351c3e9ef4693d8e8e3f245db0d96f",
24
24
  "size": 4761
25
25
  },
26
26
  {
27
27
  "path": "toolkit/scripts/uninstall-claude-skills.ps1",
28
- "sha256": "2c629d8316b205c6a7cd0d95959b80801b281ef62e205c10a92e3a2568eb8b41",
28
+ "sha256": "61dd1e2c41cb7e09ef4e197c38989dc72a836bc663a40ddeeb099733f01261e3",
29
29
  "size": 1901
30
30
  },
31
31
  {
32
32
  "path": "toolkit/scripts/uninstall-codex-skills.ps1",
33
- "sha256": "fdb9631a80ecfb0d986a52a2833e88bf15c5303ab654d35bad6d64cca43046e8",
33
+ "sha256": "092b5633861406e0e83fc62ecb261a678237197fd500933eb7a3d5915ed826e4",
34
34
  "size": 2428
35
35
  },
36
36
  {
@@ -45,8 +45,8 @@
45
45
  },
46
46
  {
47
47
  "path": "toolkit/SDTKOPS_TOOLKIT.md",
48
- "sha256": "58cfc74a11b8a0a18d0113a12e0e0b7a1188b253f7d19ff259d551914a831c4e",
49
- "size": 7968
48
+ "sha256": "3ad54f730fefdc94e5107a49b3d4a64e4169b035ceae90a4830d6f48944b2177",
49
+ "size": 8142
50
50
  },
51
51
  {
52
52
  "path": "toolkit/skills/ops-backup/references/backup-script-patterns.md",
@@ -108,6 +108,46 @@
108
108
  "sha256": "6f38c9b2ab972f272fb86e17926585a9a254a1c48c8454459a61315d4bd81d81",
109
109
  "size": 5617
110
110
  },
111
+ {
112
+ "path": "toolkit/skills/ops-framer-deploy/framer-deploy.config.example.json",
113
+ "sha256": "282645df98f039cbf8b1b29f52fe74b31c83790b1452240968e10a477947a884",
114
+ "size": 4410
115
+ },
116
+ {
117
+ "path": "toolkit/skills/ops-framer-deploy/scripts/framer-extract.mjs",
118
+ "sha256": "76ea39d3cedf8c5ac8fede0c49b6807d1546e4934d673eae00b86120e9f268a1",
119
+ "size": 12001
120
+ },
121
+ {
122
+ "path": "toolkit/skills/ops-framer-deploy/scripts/framer-install.mjs",
123
+ "sha256": "ab50e9ce83a0aee4f7a41897f60fb71aea9ef96ef7f8dc0aa1e9ebe33af6dcee",
124
+ "size": 4846
125
+ },
126
+ {
127
+ "path": "toolkit/skills/ops-framer-deploy/scripts/framer-place.mjs",
128
+ "sha256": "0f07f8fc469b06220e820b738a7d362323d96bf765055caf9255bc588d89b91f",
129
+ "size": 6876
130
+ },
131
+ {
132
+ "path": "toolkit/skills/ops-framer-deploy/scripts/framer-scaffold.mjs",
133
+ "sha256": "8ba082d86d92e8cf01168246264092b8543806dbc76bdf378863ce3f5955e2dc",
134
+ "size": 10263
135
+ },
136
+ {
137
+ "path": "toolkit/skills/ops-framer-deploy/scripts/framer-verify.mjs",
138
+ "sha256": "9da1f281c59f216238bf379afa43511340b03a7da99961ed5ff6d8f9ba5fcb06",
139
+ "size": 7169
140
+ },
141
+ {
142
+ "path": "toolkit/skills/ops-framer-deploy/scripts/lib/config.mjs",
143
+ "sha256": "23f917c38b7772f792c38f91955faaf94c0f0b5b38b654a3b4a1da468a262ca3",
144
+ "size": 7293
145
+ },
146
+ {
147
+ "path": "toolkit/skills/ops-framer-deploy/SKILL.md",
148
+ "sha256": "245e40f0afb5bc4973f149badc7c9b575865fc0fb85dc71a089f6acfba52791e",
149
+ "size": 8470
150
+ },
111
151
  {
112
152
  "path": "toolkit/skills/ops-incident/references/communication-templates.md",
113
153
  "sha256": "f6102d127e47861068b285ebbbb2045e4c3dc8cd9af73b3c975f285f2141639e",
@@ -1,12 +1,12 @@
1
- 5c76955ecabfae64759c11a3ee0fa777b1e0c0f78bdd177ae8f04340cd572e4b toolkit/AGENTS.md
1
+ 77d09c309061991343ef7ae42181afb7b8f9684c74a3f3a10166c93dbcec6508 toolkit/AGENTS.md
2
2
  e79e1ab404abf83a4f90838a2f6450c387ada7e65b137a18f70f0cab74fc14f0 toolkit/install.ps1
3
- 5eae77f4d14b81d56c3c109f563fefafd1967d85093ff1b192293fe438aeabe5 toolkit/scripts/install-claude-skills.ps1
4
- 68eb662bc9b8906882d32f6cd1247238f6ae663137a489f18054a75724cd1e81 toolkit/scripts/install-codex-skills.ps1
5
- 2c629d8316b205c6a7cd0d95959b80801b281ef62e205c10a92e3a2568eb8b41 toolkit/scripts/uninstall-claude-skills.ps1
6
- fdb9631a80ecfb0d986a52a2833e88bf15c5303ab654d35bad6d64cca43046e8 toolkit/scripts/uninstall-codex-skills.ps1
3
+ 53fddfb0424676929f72d844faa319f2e4eba9252f1c2c31fd8780c9a61f224a toolkit/scripts/install-claude-skills.ps1
4
+ a3451bd0978790d2bca9eecce1f2ab79e9351c3e9ef4693d8e8e3f245db0d96f toolkit/scripts/install-codex-skills.ps1
5
+ 61dd1e2c41cb7e09ef4e197c38989dc72a836bc663a40ddeeb099733f01261e3 toolkit/scripts/uninstall-claude-skills.ps1
6
+ 092b5633861406e0e83fc62ecb261a678237197fd500933eb7a3d5915ed826e4 toolkit/scripts/uninstall-codex-skills.ps1
7
7
  712382d838a18b6cc6a5285b3c536fac74138c752a3fa1fd318828b19ece6b8f toolkit/sdtk-spec.config.json
8
8
  2a306c1609499fb4910b86d5ec6e8c796e0cdf72c5f97fe3df9c1388ac62b913 toolkit/sdtk-spec.config.profiles.example.json
9
- 58cfc74a11b8a0a18d0113a12e0e0b7a1188b253f7d19ff259d551914a831c4e toolkit/SDTKOPS_TOOLKIT.md
9
+ 3ad54f730fefdc94e5107a49b3d4a64e4169b035ceae90a4830d6f48944b2177 toolkit/SDTKOPS_TOOLKIT.md
10
10
  1cd81e12cebdb2be528803e2d8afe43959aab1493e55499af529b99ec566a56c toolkit/skills/ops-backup/references/backup-script-patterns.md
11
11
  76e8385190d967bf98b3cafbbf8925d9b9c656ee7a7ed66ff51285b6459ebff1 toolkit/skills/ops-backup/SKILL.md
12
12
  d27e47b0c832656c2835e3d3e32dae7c86419014199439b10fc6823956324716 toolkit/skills/ops-ci-cd/references/pipeline-examples.md
@@ -19,6 +19,14 @@ d70b59d276edf5c6c8aebb5fc669b8f6d04673fc8e8561cbaf4d7e5fb9f4e2f2 toolkit/skills
19
19
  d5f58322afebcf5c3a110b02de0d2eec4494f9ed9d358b113b6717275c3524af toolkit/skills/ops-debug/SKILL.md
20
20
  c2cacc94ffba4d7ef84e635c2078e08abb8d52f79afbbb1534661c0e0cf9bda6 toolkit/skills/ops-deploy/SKILL.md
21
21
  6f38c9b2ab972f272fb86e17926585a9a254a1c48c8454459a61315d4bd81d81 toolkit/skills/ops-discover/SKILL.md
22
+ 282645df98f039cbf8b1b29f52fe74b31c83790b1452240968e10a477947a884 toolkit/skills/ops-framer-deploy/framer-deploy.config.example.json
23
+ 76ea39d3cedf8c5ac8fede0c49b6807d1546e4934d673eae00b86120e9f268a1 toolkit/skills/ops-framer-deploy/scripts/framer-extract.mjs
24
+ ab50e9ce83a0aee4f7a41897f60fb71aea9ef96ef7f8dc0aa1e9ebe33af6dcee toolkit/skills/ops-framer-deploy/scripts/framer-install.mjs
25
+ 0f07f8fc469b06220e820b738a7d362323d96bf765055caf9255bc588d89b91f toolkit/skills/ops-framer-deploy/scripts/framer-place.mjs
26
+ 8ba082d86d92e8cf01168246264092b8543806dbc76bdf378863ce3f5955e2dc toolkit/skills/ops-framer-deploy/scripts/framer-scaffold.mjs
27
+ 9da1f281c59f216238bf379afa43511340b03a7da99961ed5ff6d8f9ba5fcb06 toolkit/skills/ops-framer-deploy/scripts/framer-verify.mjs
28
+ 23f917c38b7772f792c38f91955faaf94c0f0b5b38b654a3b4a1da468a262ca3 toolkit/skills/ops-framer-deploy/scripts/lib/config.mjs
29
+ 245e40f0afb5bc4973f149badc7c9b575865fc0fb85dc71a089f6acfba52791e toolkit/skills/ops-framer-deploy/SKILL.md
22
30
  f6102d127e47861068b285ebbbb2045e4c3dc8cd9af73b3c975f285f2141639e toolkit/skills/ops-incident/references/communication-templates.md
23
31
  fda6d9cadc5a3757e5559798a67716a6356809735b076d47d6bd99a993b71b99 toolkit/skills/ops-incident/references/postmortem-template.md
24
32
  358644dcd477fe32d3368ced5c9da30663ae3d54fdd5e825ae3e56327f7f6f2d toolkit/skills/ops-incident/references/runbook-template.md
@@ -166,6 +166,7 @@ Use the suite products according to task intent:
166
166
  - CI/CD changes
167
167
  - monitoring, incident response, security-infra, backup, compliance
168
168
  - entry: `ops-discover` (when boundary is unclear), `ops-plan`, `ops-deploy`, `ops-incident`, `ops-monitor`, `ops-backup`, `ops-verify`, `ops-debug`
169
+ - vendor-specific: `ops-framer-deploy` when the deploy target is a Framer project
169
170
 
170
171
  Cross-cutting capabilities (not a linear lane; usable across every phase):
171
172
 
@@ -33,7 +33,7 @@ The current public package is:
33
33
  - Latest published version lookup: `npm view sdtk-ops-kit version`
34
34
 
35
35
  The truthful current operational surface after `init` is skill-driven:
36
- - the 15 `ops-*` skills remain the real operating surface
36
+ - the 16 `ops-*` skills remain the real operating surface
37
37
  - `ops-discover` remains a skill, not a CLI command
38
38
  - `ops-verify` remains the required closing skill for every canonical journey
39
39
  - `generate` remains unsupported and deferred
@@ -138,6 +138,7 @@ Other valid but non-primary routed skills in this wave:
138
138
  | `ops-deploy` | execute deployments with health gates, rollout strategy, and rollback discipline |
139
139
  | `ops-container` | define secure image build and container orchestration patterns |
140
140
  | `ops-ci-cd` | build and manage pipelines, promotion flow, artifact handling, and secret controls |
141
+ | `ops-framer-deploy` | deploy a built HTML template into a Framer project as code components |
141
142
 
142
143
  ### 5.3 Operations
143
144
 
@@ -195,7 +196,8 @@ Use these documents by role:
195
196
 
196
197
  ## 8. Scope
197
198
 
198
- `SDTK-OPS` v1 contains 15 core skills and stays cloud-agnostic.
199
+ `SDTK-OPS` v1 contains 15 cloud-agnostic core skills, plus `ops-framer-deploy`,
200
+ the one vendor-specific skill in the set (Framer Server API).
199
201
 
200
202
  Not part of the current supported wave:
201
203
  - provider-specific packs such as AWS, GCP, or Azure variants
@@ -16,8 +16,8 @@ if (-not (Test-Path -LiteralPath $skillsSource)) {
16
16
  }
17
17
 
18
18
  $managedSkills = @(Get-ChildItem -LiteralPath $skillsSource -Directory | Sort-Object Name)
19
- if ($managedSkills.Count -ne 15) {
20
- throw "Expected 15 managed SDTK-OPS skills but found $($managedSkills.Count)."
19
+ if ($managedSkills.Count -ne 16) {
20
+ throw "Expected 16 managed SDTK-OPS skills but found $($managedSkills.Count)."
21
21
  }
22
22
 
23
23
  if ($Scope -eq 'user') {
@@ -67,8 +67,8 @@ $installedNow = @(
67
67
  Where-Object { $managedSkills.Name -contains $_.Name } |
68
68
  Select-Object -ExpandProperty Name
69
69
  )
70
- if ($installedNow.Count -ne 15) {
71
- throw "Claude skill install incomplete. Expected 15 managed skills at $skillsDest but found $($installedNow.Count)."
70
+ if ($installedNow.Count -ne 16) {
71
+ throw "Claude skill install incomplete. Expected 16 managed skills at $skillsDest but found $($installedNow.Count)."
72
72
  }
73
73
 
74
74
  if (-not $Quiet) {
@@ -81,8 +81,8 @@ if (-not (Test-Path -LiteralPath $skillsSource)) {
81
81
  }
82
82
 
83
83
  $managedSkills = @(Get-ChildItem -LiteralPath $skillsSource -Directory | Sort-Object Name)
84
- if ($managedSkills.Count -ne 15) {
85
- throw "Expected 15 managed SDTK-OPS skills but found $($managedSkills.Count)."
84
+ if ($managedSkills.Count -ne 16) {
85
+ throw "Expected 16 managed SDTK-OPS skills but found $($managedSkills.Count)."
86
86
  }
87
87
 
88
88
  $codexHome = Resolve-CodexHome -TargetScope $Scope -TargetProjectPath $ProjectPath
@@ -132,8 +132,8 @@ $installedNow = @(
132
132
  Where-Object { $expectedNames -contains $_.Name } |
133
133
  Select-Object -ExpandProperty Name
134
134
  )
135
- if ($installedNow.Count -ne 15) {
136
- throw "Codex skill install incomplete. Expected 15 managed skills at $skillsDest but found $($installedNow.Count)."
135
+ if ($installedNow.Count -ne 16) {
136
+ throw "Codex skill install incomplete. Expected 16 managed skills at $skillsDest but found $($installedNow.Count)."
137
137
  }
138
138
 
139
139
  if (-not $Quiet) {
@@ -18,8 +18,8 @@ if (-not (Test-Path -LiteralPath $skillsSource)) {
18
18
  $managedSkillNames = @(
19
19
  Get-ChildItem -LiteralPath $skillsSource -Directory | Sort-Object Name | Select-Object -ExpandProperty Name
20
20
  )
21
- if ($managedSkillNames.Count -ne 15) {
22
- throw "Expected 15 managed SDTK-OPS skills but found $($managedSkillNames.Count)."
21
+ if ($managedSkillNames.Count -ne 16) {
22
+ throw "Expected 16 managed SDTK-OPS skills but found $($managedSkillNames.Count)."
23
23
  }
24
24
 
25
25
  if ($Scope -eq 'user') {
@@ -43,8 +43,8 @@ $managedSkillNames = @(
43
43
  Sort-Object Name |
44
44
  ForEach-Object { "sdtk-$($_.Name)" }
45
45
  )
46
- if ($managedSkillNames.Count -ne 15) {
47
- throw "Expected 15 managed SDTK-OPS skills but found $($managedSkillNames.Count)."
46
+ if ($managedSkillNames.Count -ne 16) {
47
+ throw "Expected 16 managed SDTK-OPS skills but found $($managedSkillNames.Count)."
48
48
  }
49
49
 
50
50
  $codexHome = Resolve-CodexHome -TargetScope $Scope -TargetProjectPath $ProjectPath
@@ -0,0 +1,129 @@
1
+ ---
2
+ name: ops-framer-deploy
3
+ description: Deploy an HTML template to Framer as code components. Use when shipping a built static site into a Framer project -- covers project scaffolding, section-to-component extraction, asset ledgering, instance placement, and the Framer API constraints that are not in its docs.
4
+ ---
5
+
6
+ # Ops Framer Deploy
7
+
8
+ ## Overview
9
+
10
+ Framer marketplace templates are Framer projects, not HTML. A site that already exists as built HTML has to be moved into Framer's own model, and the naive route -- rebuilding it by hand on the canvas -- both loses fidelity and cannot be repeated.
11
+
12
+ This skill ships the pipeline that does it by script instead: build once, extract sections into code components, upload assets with a URL ledger, install, place instances in document order, publish. Everything except publishing is automated.
13
+
14
+ ## The Iron Law
15
+
16
+ ```
17
+ NOTHING SHIPS TO FRAMER THAT HAS NOT BEEN RENDERED AND MEASURED FIRST
18
+ ```
19
+
20
+ Every failure this skill documents shared one shape: **no error, plausible-looking output, wrong result.** Reading generated code never caught any of them. Rendering it did.
21
+
22
+ ## When to Use
23
+
24
+ Use for:
25
+ - moving a built HTML site into a Framer project
26
+ - keeping a Framer edition in sync with an HTML source that keeps changing
27
+ - template work destined for the Framer marketplace
28
+
29
+ Do not use for:
30
+ - designing a page inside Framer from scratch (no API reaches that)
31
+ - sites whose value is Framer-native components a buyer will edit on canvas
32
+
33
+ ## Prerequisites
34
+
35
+ `~/.sdtk/framer.env`, chmod 600, never in the repo and never on argv:
36
+
37
+ ```
38
+ FRAMER_API_KEY=<key>
39
+ FRAMER_PROJECT_URL=https://framer.com/projects/<name>--<id>
40
+ ```
41
+
42
+ `framer-api` (pin the version you verified against) and `playwright-core` with a Chromium available.
43
+
44
+ ## Pipeline
45
+
46
+ ```
47
+ build HTML -> framer-scaffold -> framer-extract -> [wire-*] -> framer-verify
48
+ |
49
+ framer-install <-----------+
50
+ |
51
+ framer-place
52
+ |
53
+ Publish (Framer editor, manual)
54
+ ```
55
+
56
+ ```bash
57
+ cp framer-deploy.config.example.json framer-deploy.config.json # then edit
58
+ node framer-scaffold.mjs --apply # pages, breakpoints, styles, assets
59
+ node framer-extract.mjs --page=index.html # sections -> components/
60
+ node wire-*.mjs # re-apply any JS behaviour (see below)
61
+ node framer-verify.mjs # render each one, compare to its page
62
+ node framer-install.mjs --apply # upload + Framer's own lint/typecheck
63
+ node framer-place.mjs --apply # instances onto pages, in order
64
+ ```
65
+
66
+ Order matters and is not cosmetic: each `wire-*.mjs` patches what the extractor just wrote, so re-extracting without re-running them silently reverts those components to inert.
67
+
68
+ ## <HARD-GATE> Before install
69
+
70
+ Do not run `framer-install.mjs --apply` unless all are true:
71
+ - `framer-verify.mjs` passes, or every exceedance is a per-component tolerance with a screenshot-confirmed cause
72
+ - every asset marker resolves (the installer refuses unresolved markers -- do not work around it)
73
+ - components carrying JS behaviour have had their wiring script re-run since the last extraction
74
+
75
+ ## <HARD-GATE> Before publish
76
+
77
+ - read one installed file's content back FROM FRAMER (`getCodeFiles()` -> `content`) and confirm what you think you shipped is what is there
78
+ - confirm no unresolved markers, no leftover placeholder tokens
79
+ - Framer's lint + typecheck clean on every file
80
+
81
+ ## Framer API constraints that are not in the docs
82
+
83
+ Each of these cost a live bug. They are the reason this skill exists as more than a script folder.
84
+
85
+ | Constraint | What happens if you do not know it |
86
+ |---|---|
87
+ | **Agent API is unreachable over a server connection** | `startAgentConversation` and siblings exist in the SDK types (shared with the in-editor plugin runtime) but none are exposed to `connect(url, key)`. There is no "describe the page and Framer builds it" path. |
88
+ | **`parentId` only resolves same-session nodes** (`@alpha`) | A frame read back from a pre-existing page is rejected with "Parent node not found", is not returned by `getNode()`, and enumerating frames first does not help. Re-create empty pages in-session before placing. |
89
+ | **Breakpoints inherit from the base frame** | Placing per breakpoint yields N copies of everything. Place into the base only. |
90
+ | **`uploadImage` rejects AVIF** | Fails through every input shape the SDK accepts, while the identical WebP uploads first try. |
91
+ | **No endpoint lists image assets** | `getImage`/`getImageData` need a node already using the image. The upload-time URL is the only record -- keep a ledger or lose them. |
92
+ | **`setPluginData` caps a value at 2 kB** | One JSON blob of ~40 asset URLs exceeds it mid-write. Use one key per image. |
93
+ | **Plugin data is node-scoped** | `framer.getPluginData` does not exist over a server connection, only `node.getPluginData`. Anchor the ledger on the home page. |
94
+ | **Identity fields are plain properties** | `WebPageNode.path`, a breakpoint's `name`/`width` -- reading them via `getAttributes()` returns `undefined` with no error, so idempotency checks silently pass and everything gets created twice. |
95
+ | **Framer injects `overflow` and `isolation` via `props.style`** | Both land on the component's own wrapper div. `overflow` clips `position:absolute` dropdowns and adds a scrollbar; `isolation: isolate` traps z-index so nothing can paint above a later instance. Force both back with `!important`. |
96
+ | **Editing a code file does not publish it** | `getUnpublishedPageChanges()` tracks page changes, not code edits, so it reports 0 while the live site still serves the old file. "Installed" and "live" are different states. |
97
+
98
+ ## Wiring: what extraction cannot carry
99
+
100
+ `framer-extract.mjs` captures markup and CSS. It never captures JavaScript. Any section whose behaviour comes from a `<script>` -- a theme toggle, a tab group, a WebGL hero, a scroll-spy -- extracts as an inert copy that **looks** interactive.
101
+
102
+ Write one `wire-<component>.mjs` per such component. It re-reads the generated file and rewrites the component body to add the behaviour in a `useEffect`, torn down in the effect's cleanup. Two rules:
103
+
104
+ - **Scope every query to the component's own root**, never `document.getElementById`. Two instances on one page otherwise collide, and a document-wide `querySelectorAll` reaches into other components.
105
+ - **A control that does nothing is worse than no control.** A button that looks clickable and is inert reads as broken and survives review, because nothing errors.
106
+
107
+ Declare each page's wiring scripts in the config's `wire` array so the extractor prints the reminder.
108
+
109
+ ## Verification, and what each check is for
110
+
111
+ | Check | Catches |
112
+ |---|---|
113
+ | `framer-verify.mjs` geometry | dropped CSS rules -- the component renders but is missing a colour, a grid, or a layout mode |
114
+ | 404s treated as failures | an unresolved image, which also corrupts every measurement around it |
115
+ | Framer's own `lintCode`/`typecheckCode` | code the project will not accept, regardless of what compiles locally |
116
+ | Reading a file back from Framer | the difference between "the generator produced this" and "this is what shipped" |
117
+
118
+ Widen a per-component tolerance only with a cause you confirmed by screenshot. The legitimate one: a page embedding a local variable font Framer cannot serve, so the component substitutes a hosted family whose letterforms are a different width, and text reflows. That is what shipping looks like, not a regression.
119
+
120
+ ## <HARD-GATE> Do not
121
+
122
+ - do not hand-edit generated `components/*.tsx` -- the next extraction overwrites it
123
+ - do not put the API key on argv, in the repo, or in a log line
124
+ - do not run `framer-place.mjs --replace` against a page someone arranged by hand; the unflagged run already skips any page with content, and that guard is the only thing standing between a script and someone's layout
125
+ - do not claim the site is updated because a script said "installed" -- publishing is a separate, manual action
126
+
127
+ ## Handoff
128
+
129
+ Report with: components installed and their lint/typecheck state, verify results with real numbers (not "passed"), what was read back from Framer, and explicitly whether the site has been published or only installed.
@@ -0,0 +1,70 @@
1
+ {
2
+ "$comment": "Copy to framer-deploy.config.json next to your built site and edit. Every path is resolved relative to THIS file. Nothing project-specific lives in the scripts.",
3
+
4
+ "projectName": "my-template",
5
+
6
+ "buildDir": "./out",
7
+ "serveRoot": "./",
8
+ "outDir": "./framer/components",
9
+
10
+ "$comment_ledger": "Prefix for the per-image plugin-data keys recording uploaded asset URLs. Unique per project inside one Framer project. Changing it later orphans the ledger and forces a re-upload -- it is the only record of those URLs, since Framer has no list-images endpoint.",
11
+ "ledgerPrefix": "mytemplate.asset.",
12
+
13
+ "$comment_assets": "Framer's uploader REJECTS AVIF. Point this at .webp even if the site ships AVIF first for real browsers; Framer re-optimises on publish.",
14
+ "assetDirs": ["./out/assets", "./out/assets/thumbs"],
15
+ "assetExtension": ".webp",
16
+
17
+ "$comment_tokens": "Colour styles are parsed from this file, never retyped. themes.dark is the block your CSS treats as default; themes.light is the opt-in one. Framer requires `light` and treats `dark` as optional, so a dark-default site maps light <- its day block.",
18
+ "tokensFile": "./src/tokens.css",
19
+ "themes": { "dark": ":root", "light": "[data-theme=\"day\"]" },
20
+
21
+ "$comment_fonts": "Local @font-face families cannot ship to Framer. Substitute a family Framer serves; the script forces these with !important because the page's own :root rule is kept too and would otherwise silently win.",
22
+ "fontSubstitutions": {
23
+ "--font-display": "\"Fraunces\", ui-serif, Georgia, serif",
24
+ "--font-body": "\"IBM Plex Sans\", ui-sans-serif, system-ui, sans-serif"
25
+ },
26
+ "fontImport": "@import url(\"https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400;9..144,500&family=IBM+Plex+Sans:wght@400;500;600&display=swap\");",
27
+
28
+ "textStyles": [
29
+ { "name": "Display/Hero", "tag": "h1", "family": "Fraunces", "weight": 500, "size": 77, "lineHeight": "0.98em", "letterSpacing": "-0.01em" },
30
+ { "name": "Body", "tag": "p", "family": "IBM Plex Sans", "weight": 400, "size": 17, "lineHeight": "1.6em" }
31
+ ],
32
+
33
+ "$comment_breakpoints": "The base (widest) frame is created with the page. These are added on top. Place instances into the BASE only -- smaller breakpoints inherit.",
34
+ "breakpoints": [
35
+ { "name": "Tablet", "width": 810, "viewportHeight": 1080 },
36
+ { "name": "Phone", "width": 390, "viewportHeight": 844 }
37
+ ],
38
+
39
+ "viewport": { "width": 1440, "height": 900 },
40
+
41
+ "$comment_tolerance": "Per-component height tolerance for framer-verify.mjs, default 0.04. Only ever widen one with a reason you have confirmed by screenshot -- a substituted font whose letterforms are a different width is the legitimate case.",
42
+ "verifyTolerance": { "MyTestimonial": 0.16 },
43
+
44
+ "pages": [
45
+ {
46
+ "file": "index.html",
47
+ "path": "/",
48
+ "$comment_sections": "Document order. `id` becomes the component's CSS wrapper class (.<id>-scope). `skipVerify` for components carrying real JS behaviour, which are checked by their own test instead.",
49
+ "sections": [
50
+ { "id": "nav", "selector": "nav.nav", "component": "MyHeader", "title": "Site header", "skipVerify": false },
51
+ { "id": "hero", "selector": ".hero-wrap","component": "MyHero", "title": "Hero", "skipVerify": true },
52
+ { "id": "foot", "selector": ".footwrap", "component": "MyFooter", "title": "Site footer" }
53
+ ],
54
+ "$comment_wire": "Names of wiring scripts this page's components need after extraction. Extraction only captures markup + CSS -- never JS -- so a component with real behaviour renders inert until its wiring script re-applies it.",
55
+ "wire": ["wire-header.mjs", "wire-hero.mjs"],
56
+ "$comment_place": "Placement order, defaults to `sections` order. Override when a page reuses components declared on another page.",
57
+ "place": ["MyHeader", "MyHero", "MyFooter"]
58
+ },
59
+ {
60
+ "file": "docs.html",
61
+ "path": "/docs",
62
+ "sections": [
63
+ { "id": "docsbody", "selector": ".wrap", "component": "MyDocsBody", "title": "Docs body" }
64
+ ],
65
+ "place": ["MyHeader", "MyDocsBody", "MyFooter"],
66
+ "$comment_controls": "Per-instance property-control values, applied when the instance is placed. Use for the one value that legitimately differs per page rather than duplicating a component.",
67
+ "controls": { "MyHeader": { "getStartedHref": "index.html#pricing" } }
68
+ }
69
+ ]
70
+ }